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Introduction 



This ViewPoint Programmer's Manual is written for programmers who are developing 
applications to nm on ViewPoint software. Viewpoint's open architecture philosophy 
allows applications to be developed easily. 

You will find this manual useftil only if you are already a Mesa programmer. You should 
have completed the Mesa Course and be familiar with the contents of the XDE User's 
Guide (610E00140) and the Mesa Language Manual (610E00170). You should also be 
familiar with the facilities described in the Pilot Programmer's Manual (610E00160) and 
the Filing Programmer's Manual contained in the Services Programmer's Guide 
(610E00180). 

The ViewPoint Programmer's Manual gives you the information you will need to 
implement the user interface of an application that runs on ViewPoint. This includes how 
to: 

• Represent applications as icons. 

• Interact with the mouse and keyboard to process the user's instructions. 

• Create folder-like containers. 

• Create property sheets. 

• Create menus. 

• Paint pictures and text on the display. 

• Create programmable keyboards. 

• Represent and manipulate multinational text. 

It does not provide you with Mesa, Pilot, or Services-specific information. 
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1.1 Document Structure 

This introductory chapter describes the physical manual Itself, how it is organized, who 
should read it, how it should be read, and why. Chapter 2, Overview, describes VlewPoint 
and discuss its history and overall design. 

Chapter 3, The Programmer's Guide, tells how to use the VlewPoint interfaces. It describes 
concepts essential to understanding VlewPoint and describes the facilities that are 
available. The most common interfaces are briefly discussed and grouped by application. 
All of the VlewPoint interfaces, with a short summary, are listed alphabetically at the end 
of the chapter. 

The individual interface chapters are arranged alphabetically in Chapters 4 through 59. 
These chapters give detailed descriptions of the interfaces that VlewPoint provides. Each 
interface chapter begins with an overview that explains the concepts behind the interface 
and the important data types that it manipulates. The second section of each chapter 
describes the actual items of the Mesa interface and groups them by function. The third 
section explains typical ways of using the interface and often contains programming 
examples. The fourth section is the index of interface items. Within an interface chapter, 
the items of the broadest interest are presented first; more specialized items follow later. 

Appendix A presents the system TIP Tables, references are in Appendix B, Appendix C 
contains a list of well-known atoms, and Appendix D contains a listing of public symbols. 

1.2 Getting Started 

Chapters 1, 2, and 3 of the ViewPoint Programmer's Manual should be read in order. 
Within Chapter 3, you will sometimes be guided to various sections in task-relative rather 
than page- relative order. Chapters 4 through 59 (the interface chapters) can be read in any 
order, depending on your need. 
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2.1 What Is Viewpoint? 

ViewPoint is a collection of facilities for writing application programs that run on a 
personal workstation with a high-resolution bitmap display. It supports an open-ended 
collection of applications, providing a framework and a set of rules that allow these 
independent applications to be integrated. It has an advanced user interface that also 
allows applications to be easily adapted for users in other countries. 

Throughout this document, the term user describes a person who interacts with the 
applications built on ViewPoint via the mouse and keyboard. Programs cannot predict or 
control user actions. The term c/ienf describes programs that use the facilities described in 
this document. The client may act as a result of some user action, but the behavior of the 
client is the result of a program and under control of its implementor. 

2.1.1 User Abstractions 

ViewPoint uses several abstractions that are part of the advanced user interface pioneered 
by the Star Workstation: 

• /cort5 and Desktop. Icons that represent objects on a desktop are one basic abstraction. 
These objects can represent either functions or data. Data icons, such as a document, 
represent objects on which actions can be performed. Function icons, such as a printer, 
represent objects that perform actions. In the metaphor, they are on the desktop that 
also serves as the background for their display. With ViewPoint, clients may create 
new icons that provide additional functions within the desktop metaphor. 

• Windows. Windows are rectangular areas on the screen that display the contents of an 
icon when it is opened. Each window has a header containing the name of the window's 
icon and a set of commands. The window also contains scroll bars that scroll the 
contents of the window vertically and horizontally. 

• Property Sheets. Property sheets are displayed forms that show the properties of an 
object. They contain several types of parameters, including state parameters, which 



2-1 



2 



Overview 



may be on or off; choice parameters, which have a set of mutually exclusive values; and 
text parameters. 

• Selection. The selection is an object or body of data identified by the user. It is the 
target of user actions; there can be only one selection at any one time. It can be a string 
of text that the user may then delete, copy, or change the properties of. It can be an icon 
on the desktop that is moved to a printer icon for printing or opened to display its 
contents. In general, it can be almost any piece of data that can be represented on the 
screen. 

2.1^ Client Abstractions 



To implement the above user abstractions and to provide some building blocks for 
developing applications, ViewPoint uses several client abstractions: 

• Containee and StarDesktop. Containee is an application registration facility that 
associates an application with a file type. Registering an application consists of 
providing procedures that paint iconic pictures and perform various operations. 
StarDesktop, using the desktop metaphor, displays the desktop window and iconic 
pictures for each file found in a particular directory. 

• Client Windows. The client window abstraction is more primitive than the user window 
abstraction. The client window abstraction serves to isolate applications from the 
physical display and each other. A window can be thought of as a quarter of an infinite 
plane. Within that space, the client is called upon to display the contents of the window 
without regard to any other applications' windows. Windows may be linked to form a 
tree structure. A user's window is typically composed of a number of small client 
windows-one for the header, one for each scroll bar, and so forth. 

• Menus. Mentis are sequences of named commands, each consisting of a text name and a 
procedure. Menus may be displayed to the user in several forms, such sis in a pop-up 
menu or as window shell header commands (see below). 

• Window Shells. The user window abstraction is implemented by window shells. They 
provide the header, scroll bars, and body windows. The body windows are windows the 
client uses to display the content of an application. The commands in the header are 
menus. 

• Form Windows. Form windows are the client abstraction that provides the basis for the 
user property sheet Form windows allow form items in a window to be created and 
manipulated. There are several types of items: boolean items, choice items, text items, 
numeric text items, command items, form and window items. Window items allow the 
client to implement its ovm type of item. The property sheet user abstraction is 
implemented by putting a form window inside a window shell. 
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• Container Windows. Container windows implement a window that contains a list of 
items. Clients supply the source of items and the container window handles that 
display the contents in a window and interact with the user. 

• Selection. The client selection abstraction is a framework in which a client can 
manifest itself as the holder of the user's current selection while other clients 
interrogate the selection and request that it be converted to a variety of data types. 
Viewpoint defines several selection conversion types, but the selection framework 
allows clients to define additional conversion types. The selection is the principal 
means by which information is transferred between different applications. 



2.1.3 System Structure 



Viewpoint's architecture contains a small set of public interfaces that provide the basic 
facilities for building workstation applications. Facilities are included in ViewPoint for 
several reasons. Some facilities implement system-wide features, such as the window 
package. If several applications tried to implement their own window packages, chaos 
would result. Facilities are also included in Viewpoint to provide a consistent user 
interface, such as form windows and property sheets. A final reason for including facilities 
is to provide packages that are useful to many clients, such as the simple text facilities. As 
ViewPoint evolves, more facilities useful to a variety of clients will be added. 

The ViewPoint interfaces fall into the following general categories: 
Application registration: Containee 

Windows and display: Context, Display, StarWindowShell, Window 

Forms and property sheets: FormWindow, FormWindowlVlessageParse, PropertySheet 

User input and keyboards: BlackKeys, KeyboardKey, KeyboardWindow, Level! VKeys, 

SoftKeys,TIP,TIPStar 

Strings and messages: XChar, XCharSets, XCharSetNNN, XComSoftMessage, 

XFormat, XLReal, XMessage, XString, XTime, XToken 

Selection: Selection 

Containers: ContainerCache, ContainerSource, ContainerWindow, 

FtleContainerShell, FiieContainerSource 

Text display and editing: SimpleTextOisplay, SimpleTextEdit. SimpleTextFont 

Background management: BackgroundProcess 

Miscellaneous user interface: Attention, Cursor, MenuOata, Message Window, 

PopupMenu, StarOesktop, Undo 

Miscellaneous: Atom, AtomicProf ile. Event, IdleControi 



2.2 History 



ViewPoint is the result of past experience with Star and the Xerox Development 
Environment. In late 1982, the Star Performance and Architecture Project concluded that 
Star's monolithic system structure, in which every piece knew about every other piece, 
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hindered its performance. The monolithic structure also made it difHcuIt to develop new _ 
applications. In addition, there were hundreds of interfaces in the system but no distinction 
between public and private interfaces, which made it diSicult for programmers to learn 
how to vnrite applications in the system. 

In contrast to Star, the Xerox Development Environment had a modular system structure 
with a small number of well-documented public interfaces It also encouraged an open- 
ended collection of applications. While it performed well and was open, the Xerox 
Development Environment did not have as consistent a user interface as Star, nor did it 
support Star's multilingual requirements. 

As a result of this study, ViewPoint was created. It has the system structure, documented 
public interfaces, and openness of the Xerox Development Environment, yet supports 
Star's user interface and multilingual requirements. 

While it was initially focused on providing a new foundation for Star, ViewPoint has 
become the basis for more software products from the Office Systems Division. It will 
evolve to replace the current foundation of the Xerox Development Environment and will 
likely support products from organizations outside the Office Systems Division. 

2.3 Philosophy and Conventions 

Viewpoint's philosophy and conventions apply both to applications that interact with the 
user and to packages that implement a facility. Some are just good system-building 
concepts. ViewPoint assumes that programs that run within it are friendly and that they 
are not trying to circumvent or sabotage the system. The system does not try to enforce 
many of these conventions but assumes that clients will adhere to them voluntarily. If 
these conventions are not followed, the system may degrade or break down altogether. 

2.3.1 Supported Public Interfaces 

Systems should be designed to export public interfaces that are well documented and 
relatively stable. By defining a set of primitive facilities and stressing their stability, 
applications are encouraged to depend on the existing ViewPoint facilities rather than on 
other applications packages. This promotes an open architecture in which applications can 
be developed and loaded with relative ease, exchanging information among themselves 
while maintaining the independence of client modules. The open architecture allows 
designing for unknown applications as well as the class of applications expected in Star. 

In keeping with an open architecture, ViewPoint does not make far-reaching assumptions 
about the applications that run above it. While ViewPoint provides facilities that make 
certain styles of applications easy, it does not preclude other styles of applications. 

2.3.2 Plug-ins 

ViewPoint is self-contained in that it does not import procedures that it expects a client to 
supply. Rather it waits, in effect, for clients to call it and state that they want to implement 
some facility. This is referred to as a plug-in approach: an application plugs itself in to a 
lower layer of software. 
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Plug-ins encourage modularity at the client level. Because ViewPoint can be run by itself 
(although it does not do much), it can also be run with just one application plugged in. Thus 
each application can be implemented and debugged individually, which simplifies system 
development. 

Plug-ins also can break a dependency that would create a complex dependency graph. For 
example, the desktop has a dependency on the applications that appear in the desktop. If 
the desktop depended directly on the applications, it would have to change every time a 
new application was created. By having the applications plug themselves into the desktop, 
the direct dependency is broken. 

2.3.3 Don't Preempt the User 

Clients should avoid dictating what the user must do. The user should be free to interact 
with different applications as desired. For example, the current selection is something that 
the user should control. It should be changed only as a result of user actions. A background 
process should not change the selection out from under the user. 

2.3.4 Don't CaU Us, We'U Call You 

Because the user is in control, a program must wait for the user to interact with it. The 
method of interacting with the user that is prevalent in terminal-oriented user interfaces 
is to get a command from the user and execute it, which results in the client regaining 
control while it awaits user input. With potentially multiple applications active 
simultaneously, the user should be free to interact with the one of his choosing. 
Viewpoint's input facilities notify a window when the user inputs to that window. 

Events are another case in which the system calls the client. For example, a client may 
need to do something when the user logs in. If the client registers a procedure with the 
appropriate event, the procedure is invoked when the event occurs. 
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This Viewpoint application programmer's guide is intended to point the programmer to the 
most important parts of the most important interfaces needed for writing an application In 
ViewPoint. 

Viewpoint is a collection of interfaces to be used for writing application programs. It is 
primarily intended to support applications like those in the ViewPoint workstation; that is, 
there is support for icons, windows, property sheets, and so forth. 

The first section (3.1 Guide) contains a jump table of the form, ''If your application does X, 
then you use interfaces A and B; also, you need to understand C and D, and you probably 
want to read section S.l.x." The subsections (3.1.x) provide more detail about A, B, C, and 
D, pointing the programmer to the most important types and procedures in an interface. 
The second section (3.2 (jetting Started) contains essential information for first-time 
ViewPoint programmers. Section 3.3 provides some flow of control descriptions for several 
common scenarios. It describes which interfaces call which client procedures when, and so 
forth. Section 3.4 discuss some programming conventions specific to ViewPoint interfaces. 
Section 3.5 contains a summary of all the ViewPoint interfaces. 

First, we briefly define an application from the user's point of view: The user sees the icons 
on the desktop and can operate on them in various ways. You can select an icon with the 
mouse and open it to display its contents. Or by selecting the icon and pressing PROPS, you 
can examine and change the icon's properties through a window called a property sheet. 
After an icon is opened, he can examine the properties of the contents and change them by 
again using the property sheet. By selecting one icon, pressing copy or MOVE, and then 
selecting another icon, he can perform various application-specific operations. This is often 
referred to as "dropping one icon onto another." Each application attaches a different 
meaning to the drop-on operation. For example, the folder takes the icon dropped onto it 
and adds it to the folder. The printing application (printer icon) prints the icon dropped 
onto it. 



From the application's point of view, an icon is just a picture that represents a file. Files 
have a file type, and an application operates on all files of the same type. Thus when the 
user selects a folder icon, he or she is actually selecting a file with file type of folder. When 
the user performs some operation on an icon, the desktop calls the appropriate application 
based on the file type of the file the selected icon represents. 
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3.1 Guide 

The following table can help you readily find a desired section. 

3.1.1 Guide to the Guide 

If your application ... See section 

^ Appears as an icon: 

- Read about icon applications in 3.2 Getting Started 3.2.2 

- Use Containee to register the icon's behavior 3.1.2 

^. Opens a window: 

- Use StarWindowShell to create a window 3. 1.3 

- Use MenuOata to construct menus 3.1.4 

... Manages the contents of a window: 

- Use Display and Window to display information 3.1.3 

- Supply a TIP. Notify Proc to process user actions 3.1.5 

- Use Selection to share data between applications 3. 1.3 

- Use Context to save data with the window 3. 1.3 

... Puts up a Property Sheet: 

- Use PropertySheet and FormWindow interfaces 3.1.6 
... Manipulates strings: 

- Use the XString interfaces (including XFormat, XToken, XChar) 3. 1.7 
Displays messages to the usen 

- Use the XMessage and Attention interfaces 3. l.d 
... Displays a list of items like a folden 

- Use the Container interfaces (ContainerWindow, ContainerSource) 3.1.9 
... Redefines the function keys: 

- Use the SoftKeys interface 3. 1. 10 
... Redefines the Black Keys: 

- Use BiackKeys and KeyBoardKey interfaces 3.1.11 
... Performs operations in a background process: 

- Use the BackgroundProcess interface 3.1.12 
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3.1.2 Contain ee 



Containee is an application registration facility. An application is a software package that 
implements the manipulation of one type of file. Containee is a facility for associating an 
application with a file type. (§3.2.2 explains how an application registers itself and is then 
invoked to perform various operations). The most important items in Containee are: 

Impiementation A record containing several client procedures. 

Setlmplementation Registers an application. 

GenericProc Client procedure called to perform OPEN, PROPS, COPY/move- 

onto, and so forth. 

PictureProc Client procedure called to display an icon picture. 

Data, DataHandle Uniquely identifies a file. 



3.1.3 Application Windows 



StarWindowSheil allows a client to create a Star-like window. A StarWindowShell window 
has a header that contains a title, commands, and pop-up menus. The window may have 
scroll bars, both horizontal and vertical. It also has interior window space that may contain 
anything the client desires. StarWindowShell also supports the notion of opening within. 

A StarWindowShell is a window (see Window interface) that is a child of the desktop 
window. A StarWindowShell has an interior window that is a child of the 
StarWindowShell and is exactly the size of the available window space in the shell, that is, 
the window shell minus its borders and header and scrollbars. The interior window may 
have child windows created by the client. These children of the interior window are called 
body windows. The client may create an arbitrary number of body windows and may 
arrange them arbitrarily. Note: Because the body windows are children of the interior 
window, they are clipped by the interior window. 

The client may manage body windows directly, including all display and notification (user 
input). Body windows can also be managed by various interfaces provided by ViewPoint, 
such as FormWindow and ContatnerWindow. These interfaces have Create procedures 
that take a body window and turn it into a particular kind of window, providing all the 
display and notification handling for the window. 

The most important items in StarWindowSheil are: 

Create Creates a StarWindowSheil window. 

CreateBody Creates a body window. 

SheilFronriChild Returns the window shell, given a body window. 

SetReguiarCommands Places commands in the header of a StarWindowSheil. 



3-3 



Programmer's Guide 



AddPopupMenu Adds a pop-up menu to the header of a StarWindowSheil. 

3.1.4 Menus 

A menu is a list of named commands. When the user selects a menu command, a client 
procedure is called. The MenuOata interface allows menu items and menus to be created. 
MenuData does not address the user interface for menus. Menu items may appear as 
commands in the header of a star window shell (5tarvvindowSh«il.SetRegularCommands). 
Entire menus may be accessed via a pop-up symbol in the header of a window shell 
(StarWindowSh«ll.AddPopupMenu). Menu Items may be added to the pop-up menu that is 
available to the user through the attention window (Attention.AddMenultem). 

The most important items in MenuOata are: 

Createitem Creates a menu item. 

MenuProc A client procedure that is called when the user selects a 

menu item. 

CreateMenu Creates a menu from an array of menu items. 

3.1.5 Managing a Body Window 

Clients can manage their own body windows. This involves handling both display and 
notification (user- input), and often includes managing the current selection. Display is 
done by providing a window display procedure. Notifications are received through a client- 
provided TIP. Notify Proc. The Selection interface manages the current selection. Arbitrary 
data associated with a window can be saved with the window by using the Context 
interface. 

3.1.5.1 Display 

The Window interface calls the client's display procedure to repaint the contents of the 
window. It is called when the window is initially made visible. It is also called when the 
window suddenly becomes more visible because an overlapping window was moved, or 
when the window is scrolled so that the part of it that was invisible before becomes visible. 
The display procedure should use the Display and/or SimpleTextOisplay interfaces to 
display bits in the window. The display procedure can be set when a window shell's body 
window is created (StarvvindowSh«ll.CreateBody) or by calling window.SetOisplayProc. 

The most important item in Window is the client's display procedure. There is no type for 
this procedure, but it is discussed in the Window interface chapter. Other important items: 

Box Defines a rectangle in a window. 

Place Defines a point in a window. 
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The most important items in Display are: 

Black Displays a black box. 

White Displays a white box. 

Invert Inverts the bits in a box. 

Bitmap Displays an arbitrary array of bits. 

The most important item in SimpieTextDisplay is: 

Stri ngi nto Wi ndow Displays a string in a window. 

3.1.5.2 TIPandTIPStar 

TIP provides basic user input facilities through a flexible mechanism that translates 
hardware-level actions from the keyboard and mouse into higher-level client action 
requests (result lists). The acronym TIP stands for terminal interface package. This 
interface also provides the client with routines that manage the input focus, the periodic 
notifier, and the STOP key. 

The basic notification mechanism directs user input to one of many windows in the window 
tree. Each window has a TiP.Table and a Tlp.NotifyProc. The table is a structure that 
translates a sequence of user actions into a sequence of results that are then passed to the 
notify procedure of the window. 



The Notifler process dequeues user events, determines which window the event is for, and 
tries to match the events in the window's Table. If it finds a match in the table, it calls the 
window's NotifyProc with the results specified in the table. If no match is found, it tries the 
next table in the window's chain of tables. If no match is found in any table, the event is 
discarded. 

TIP tables provide a flexible method for translating user actions into higher-level client- 
defined actions. They are essentially large select statements with user actions on the left 
side and a corresponding set of results on the right side. Results may include mouse 
coordinates, atoms, and strings for keyboaird character input. 

Viewpoint provides a list of normal tables that contain one production for each single user 
action. Client programmers can write their own table to handle special user actions and 
link it to system-defined tables, letting those tables handle the normal user actions. These 
system-defined tables are accessible through the TIPStar interface and are described in 
Appendix A. 

Input Focus. The input focus is a distinguished window that is the destination of most user 
actions. User actions may be directed either to the window with the cursor or to the input 
focus. Actions such as mouse buttons are typically sent to the window with the cursor. Most 
other actions, such as keystrokes, are sent to the current input focus. Clients may make a 
''^■Z window be the current input focus and be notified when some other window becomes the 

current input focus. 
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The current selection and the current input focus often go together. If the window in which 
a selection is made also expects to receive user keystrokes (fimction keys as well as black JHI 
keys), TiP.SetlnputFocus should be called at the same time as Seiection.Set is called. This is 
also the time to call SoftKey$.Push or K«yboardK«y.RegjsterClientKeyboards, if necessary. 

Modes. TIPStar also provides the notion of a global mode to support MOVE, COPY, and SAME. 
When the user presses dovm and releases the MOVE, COPY, or SAME keys, the client that 
currently has the input focus will receive the notification and should call TiPStar.SetMode. 
This changes the mouse TIP table so that atoms specific to the mode are produced rather 
than normal atoms when the user performs mouse actions. For example, in copy mode 
'*CopyModeDown'' instead of "PointDown" is produced when the user presses the left 
mouse button. This informs the client that receives the atom that it should attempt to copy 
the current selection rather than simply select something. 

The most important items in TIP are: 

NotifyProc Client procediire that is called to handle a user action. 

Results, ResuitObject Right side of the table entry that matched the user action. 
SetlnputFocus Sets a window to be the current input focus. 

The most important items in TIPStar are: 

NormaiTable Returns the chain of system-provided TIP tables. Jiiik 

SetMode Sets the entire environment into MOVE, COPY, or SameAs 

mode, thus changing the results produced for mouse clicks. 

3.1.3.3 Context 

The Context interface allows arbitrary client data to be associated with a window. Client 
data is usually allocated and associated with the window when the window is created. The 
data may be retrieved any time, such as at the beginning of the client's display procedure 
andTtP.NotifyProc. 

The most important items in Context are: 

Create Associates data with a window. 

Find Recovers the data previously associated with a window. 



3.1.5.4 Selection 



The Selection interface defines the abstraction that is the user's current selection. It 
provides a procedural interface to the abstraction that allows it to be set, saved, cleared, 
and so forth. It also provides procedures that enable someone other than the originator of 
the selection to request information relating to the selection and to negotiate for a copy of 
the selection in a particular format. 
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The Selection Interface is used by two different classes of clients. Most clients wish merely 
to obtain the value of the current selection in some particular format; such clients are 
called requestors. These programs call Convert (or maybe ConvertNumber, which in turn 
calls Convert), or Query, or Enumerate. These clients need not be concerned with many of 
the details of the Selection interface. 

The other class of clients are those that own or set the current selection; these clients are 
called managers. A manager calls s«i«ction.Set and provides procedures that may be called 
to convert the selection or to perform various actions on it. The manager remains in control 
of the current selection until some other program calls s«i«ction.Set. These clients need to 
understand most of the details of the Selection interface. 

A client that is managing its own body window will be both a selection requestor and a 
selection manager in different parts of the code. For example, when the user selects 
something in another window and copies it to the client's window, the client must call 
s«i«ction.Convert to request the value of the selection in a form appropriate to the 
application. On the other hand, when the user clicks a mouse button in the client's window, 
the client usually becomes the selection manager by calling s«l«ction.Set. 

The most important items in Selection are: 

Convert Request the value of the selection in some target form. 

Value A record containing a pointer to the converted selection 

value, among other things. 

CanYouConvert Returns true if the selection manager can convert the 

selection to a particular target type. 

Set Called by a selection manager to become the current 

manager. 

ConvertProc Manager-supplied procedure that will be called to convert 

the selection to some target type. 

ActOnProc Manager-supplied procedure that will be called to perform 

some action on the selection, such as mark, unmark, clear. 

3.1.6 Property Sheets and Form Window 

A property sheet shows the user the properties of an object and allows the user to change 
these properties. There are several different types of properties, the most common ones 
being boolean, choice (enumerated), and text. 
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From a client's point of view, a property sheet is simply a StarWindowShell with a 
Form Window as a body window. A property sheet is created by calling PropertySheet.Create, 
providing a procedure that will make the form items in the Form Window (a 
Form Window. Ma keltemsProc), a list of commands to put in the header of the property sheet, 
such as Done, Cancel, and Apply (Prop«rtySheet.Menuitems), and a procedure to call when 
the user selects one of these commands (a PropertySh««t.lVlenuitemProc). When the user 
selects one of the commands in the header of the property sheet, the client's 
Prop«rtySh««t.MenuitemProc is called. If the user selected Done, for example, the client can 
then verify and apply any changes the user made to the object's properties. 

The most important items in PropertySheet are: 

Create Creates a property sheet. 

Menuitems Used for specifying which commands to put in the header of 

the property sheet. 

MenuitemProc Client procedure called when the user selects one of the 

commands in the header. 

The most important items in Form Window are: 

Ma keltemsProc Client'procedure called to create the items in the form. 

MakeXXXltem Makes a form item. XXX can be Boolean, Choice, Text, 

Integer, Decimal, Window, TagOnly, Command. 

GetXXXItem Value Returns the current value of an item. XXX can be Boolean, 

Choice, Text, Integer, Decimal, Window, TagOnly, 
Command. 

3.1.7 XString, et al. 

The Xerox Character Code Standard defines a large number of characters, encompassing 
not only familiar ASCII characters but also Japanese and Chinese Kanji characters and 
others to provide a comprehensive character set able to handle international information 
processing requirements. Because of the large number of characters, the data structures in 
XString are more complicated than a long string's simple array of ASCII characters, but the 
operations provided are more comprehensive. 

Characters are 16-bit quantities that are composed of two 8-bit quantities, their character 
set and character code within a character set. The Character Standard defines how 
characters may be encoded, either as runs of 8-bit character codes of the character set or as 
16-bit characters where the character set and character code are in consecutive bytes. (See 
the XChar chapter for information and operations on characters.) 

ViewPoint provides a string package consisting of several interfaces that support the Xerox 
Character Code Standard. XString provides the basic data structures for representing 
encoded sequences of characters and some operations on these data structures. XFormat 
converts other types into XStrings. XToken parses XStrings into other types. XChar defines 
the basic character type and some operations on it. XCharSets 
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enumerates the character sets defined in the Standard. A collection of interfaces 
enumerate the character codes of several common character sets (XCharSetNNN). XTime 
'^iw^ provides procedures to acquire and edit times into XStrings and XStrings into times. 

3.1.8 XMessage and Attention 

XMessage supports translation into other languages of text displayed to the user. It does 
not include any string constants in the code of an application. Rather, all the string 
constants for an application are declared in a separate module and registered with 
XMessage. Then whenever the application needs a string constant, it obtains it by calling 
XMessage. Get. Several commonly used messages such as "Yes**, "No", and days of the 
week are defined in XComSoftMessage. 

The most important items in XMessage are: 

Get Retrieves a message. 

RegisterMessages Registers all the messages for an application. 

The Attention interface provides a global mechanism for displaying messages to the user. 
Attention provides procedures to post messages to the user in the attention window, clear 
the attention window, post a message and wait for confirmation, and so forth. 

The most important items in Attention are: 

Post Posts a message in the attention window. 

Clear Clears the attention window. 

formatHandie XForfnat.Handle that may be used to format strings into the 

attention window. 

3.1.9 Containers 

The Container interfaces (ContainerSource, ContainerWindow, FileContainerSource, 
FiieContainerSheii, and ContalnerCache) provide the services needed to implement an 
application that appears as an ordered list of items to be manipulated by the user. Star 
Folders are a typical example of such an application. 

Figure 3-1 shows the relationships among the various interfaces and potential clients. 
Each interface is described below, followed by a discussion of which interfaces an 
application might need to use. 
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Figure 3.1 Container Interface Dependencies 



The ContainerWindow interface takes a window and a ContainerSource and makes the 
window behave like a container. It maintains the display and manages scrolling, selection, 
and notifications. Note: This interface does not depend on NSFiie. 



A container source is a record of procedures that implement the behavior of the items in a 
container and the behavior of the container itself- ContainerWindow obtains the strings of 
each item by calling one of these procedures. ContainerWindow also performs user 
operations on items (such as open, props, delete, insert, take the current selection, and 
selection conversion) by calling other procedures in the record. A container source can be 
thought of as a supply (source) of items for a container window. The ContainerSource 
interface defines each of the procedure types that a container source must implement. 
ContainerSource contains types only. 

ContainerCache provides the implementor of a container source with an easy-to-use cache 
for storing and retrieving the strings of each item and some client-specific data about each 
item. 

FileContainerSource provides an NSFile-backed container source. It takes an 
NSFtle.Reference for a file that has children, and each child file becomes an item of the 
container. Facilities are provided to specify the columns based on NSFiie attributes. 

The FileContainerShell interface takes an NSFiie and column information (such as 
headings, widths, formatting) and creates a FileContainerSource, a StarWindowShell, and ^gn^ 
a container window body window. Most NSFile-backed container applications can use this 
interface, which greatly simplifes the writing of those applications. 
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Each of the items in a container must behave like to a file on the desktop; that is, each item 
must be able to be opened, show a property sheet, take a selection, and so forth. However, 
the items need not be backed by files. If the container is backed by an NSFile that has 
children, then the FileContainerSHeil interface is the only interface the client needs to use. 
Otherwise, the client must implement a container source and make most of the calls that 
the FiieContainerSheil implementation makes; that is, starWindowSh«ii. Create, 
StarWindowSh«lt.CreateBody,Contain«rWindow.Create. 



3.1.10 SoftKeys 



. The SoftKeys interface provides for client-defined function keys designated to be the 
isolated row of function keys at the top of the physical keyboard. It also provides a 
SoftKeys window whose "keytops** may be selected with the mouse to simulate pressing the 
physical key on the keyboard. Such a window is displayed on the user's desktop whenever 
an interpretation other than the default SoftKeys interpretation is in effect. (The default is 
assumed to be the functions inscribed on the physical keys.) 



The most important items in SoftKeys are: 

Labels, Label Record Strings to display on the keytops in the SoftKeys window. 
Push Install a client-specific interpretation for the soft keys. 

Remove Remove a previously installed interpretation. 

3.1.11 CUent-DefiUied Keyboards 



KeyboardKey is a keyboard (the central set of black keys on the physical keyboard) 
registration facility. It provides clients with a means of registering system- wide keyboards 
(available all the time, like English, French, European), a special keyboard (like 
Equations), and/or client-specific keyboards (those that are available only when the client 
has the input focus). The labels from these registered keyboards are displayed in the 
softkeys window when the user holds the KEYBOARD key down. 

The Black Keys interface provides the data structures that define a client keyboard. 

The most important items in KeyboardKey are: 

■ 

AddToSystem Keyboards Adds a keyboard to the system keyboards. 
RegisterCUentKeyboards Establishes the keyboards available to the user. 

The most important items in BlackKeys are: 

Keyboard, Key board Object A keyboard interpretation. 
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3.1.12 BackgroundProcess 

The BackgroundProcess interface provides basic user feedback and control facilities to 
clients that want to run in a process other than the the Notifier process (see the Notiiler 
section below). Once registered with BackgroundProcess, the client process can use 
Attention to post messages and check to see if the process has been aborted by the user. The 
user can look at the messages posted by the process and abort the process. The primary 
procedure in BackgroundProcess is ManageMe, which is typically the Hrst procedure 
called from a background process. 

3.2 Getting Started 

This section is a guide for programmers who have never used the ViewPoint interfaces. It 
shows how two common types of applications are written using ViewPoint. 

A user can invoke a program in the ViewPoint environment in two ways. First is to select 
an icon and press a fimction key such as OPEN, PROPS, COPY, or MOVE. This type of program 
is called an icon application. Second, the user may simply select an item in the attention 
window's pop-up menu. For example, in OS 5, a Show.Size command reports on the size of 
the selected icon's file. The following sections describe how to write each of these t3rpes of 
programs. 

3.2.1 Simplest Application 



The simplest way to get a program running in the Viewpoint environment is to have the 
program add an item to the attention window's pop-up menu. When the user selects that 
item, the program is called. See the SampleBWSTool for an example of this type of 
application. Excerpts from SampleBWSTool: 

I nit: PROCEDURE ■ { 

sampleTool: xstnng.ReaderBody 4>xstring.FromSTRlNG['*Sampie ToorU; 
Attention.AddMenultem [ 
M«nuOata.Createitem [ 

zone: sysZ, 

name: @sampleTool, 

proc: MenuProc]]; 

}; 

~ Mainline code 
InitO; 

When the application is started, its startup (mainline) code creates a MenuOata.ltemHandle 
by calling MenuOata.Createitem and then adds this item to the attention window's menu by 
calling Attention-AddMenultem. Now the MenuProc passed to MenuOata.Createitem is called 
when the user selects the Sample Tool item in the attention window's pop-up menu. The 
MenuProc can then do whatever is appropriate for the application. 
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3.2.2 Icon Application 

Getting an icon application running in ViewPoint is a little more complex. The basic idea is 
that an application operates on flies of a particular type. When an application is started, it 
registers its interest in files of that type. Whenever the user operates on a file of that type, 
the application gets called. Here is a skeletal example of some application code; the full 
explanation follows: 

— Constants and global data 

samplelconFiieType: NSFii«.Type « . . .; 

oidimpi, newimpi: Contam«e.lmplementation «~ []; 

— Containe«./mp/ementat/on procedures 

GenericProc:contain««.GenericProc ■ { 
SELEaatom from 

canYouTakeSeiection « > . . . 
takeSeiection • > . . . 
takeSelectionCopy ■ > . . . 
open « > . . . 
props ■ > . . . 

ENDCASE ■ > . . . 

PictureProc:contain««.PictureProc « { 
''mrn^ Dispiay.Bitmap [. . .]; 

};' 

— Initialization procedures 

InitAtoms: procedure ■ { 

open ^-Atom.MakeAtomCOpen"^; 
props 4- Atom.MakeAtom[''Prop$'*L]; 

canYouTakeSeiection ^Atoin.MakeAtom[*CanYouTakeS€lection"L]; 
takeSelection 4- Atom.MakeAtom("TakeSelection ** L] ; 
takeSelectionCopy «- Atom.MakeAtom['*TakeSelectionCopy'*L]; 

>; 

FindOrCreatePrototypeiconFile: procedure « { . . .}; 

Setlmpiementation: procedure a { 
newlmpl.genericProc GenericProc; 
newlmpl.pictureProc PictureProc; 

oldlmpl 4->Contain««.Setlmplementation [ sampieiconFiieType, newimpi ]; 

}; 

Mainline code 
InitAtomsG; 

J FindOrCreatePrototypeiconFileO; 

Setlmplementation(]; 
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The most important thing to note in the above example is the Setlmplementation 
procedure and the call toContainee.Setlmplementation in particular. This call associates the 
application's implementation (newimpi) with a particular file type (samplekonFileType). 
This implementation is actually a Containe«.lmplementation that is a record which contains 
procedures. Whenever the user operates on files of type samplekonFileType, the 
procedures in the Implementation record are called. An understanding of how this works 
requires an understanding of how the ViewPoint desktop implementation operates. 

First, some background about NSFiies. All NSFtles have: 

• A name 

• A file type (L0N<3 CARDINAL) 

• A set of attributes, such as create date 

• Either: 

• Content, such as a document 

• Children that are also NSFiies, such as a folder. 



An NSFile that has children is often called a directory. Fine point: anNSFile can actually have both 
content and childreiu however, to simplify this diacussion, this point is ignored. Note: Because the children 

of an NSFile can themselves have children, NSFile supports a hierarchical file system. 

A Viewpoint desktop is an NSFile that has children. An on-screen icon picture represents 
each child file of the desktop's NSFile The desktop display of rows of "icons'* is an illusion. _ 
The word icon is in quotes because, from the programmer's point of view, there really is no 
such thing as an icon. The only things that really exist are files (NSFiies), icon pictures, and 
application code. 

Immediately after logging on, the desktop implementation enumerates the child files of the 
desktop file and calls an application's Contain««.PictureProc for each child file, based on the 
child file's type. Each application's Contain««.PictureProc should then display the icon 
picture for that file. 

After logon is complete and the desktop is displayed, the desktop implementation receives 
user actions such as mouse clicks and presses of the OPEN or PROPS keys. For example, 
assume the user selects an icon picture amd presses OPEN. The desktop implementation 
determines the file type for the file represented by the icon picture the user selected and 
then calls the Contain««.GenericProc for the application that operates on files of that type, 
requesting that the application open the icon. It also passes the application a unique 
identifier for the particular file selected. At this point, the application can do whatever is 
appropriate for that application. Typically, the application opens the file, reads some data 
out of it, creates a StarWindowShell, and displays the contents of the file in the window in 
some application-specific form. 

The desktop implementation does not call an application directly. Rather, ViewPoint 
maintains a table of file-type/Contain««.Jmplementation pairs. When an application calls 
Containee. Setlmplementation, an entry is added to the table. When the desktop Jfllki 
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implementation calls an application, it obtains the Containee. Implementation for the 
application by looking it up in the table (it actually calls Containe«.Getimplementation). 

3.2.3 Operational Notes 

To write an icon application, a programmer must obtain a unique file type. Contact your 
Viewpoint consultant to obtain one. 

In the example above, the application in its initialization code checks to be sure a prototype 
file exists and, if not, creates one. This usually involves creating a file with the proper file 
type for this application. This allows the user to get started with the application, usually by 
copying the blank prototype out of a special folder of prototypes. 

Note: There is a clear distinction between a prototype file for an application and a bed file 
that contains the code for the application. All bed files are of the same type, while each 
prototype file is different for each application. 

3.3 Flow Descriptions 

The following flow descriptions are intended to show how everything is related. For each 
example scenario, the exact sequence of calls is described, including ViewPoint interfaces 
and clients. 

3.3.1 Select an Icon 

The user points at an icon on the desktop. 

• When the mouse button goes down over an icon picture, the notification goes to the 
desktop implementation's TIP. Notify Proc. The NotifyProc will be passed a window.Place 
and a '^PointDown" atom. The desktop implementation determines what file is 
represented by that icon picture. Fine point: The desktop implementation maintains a mapping from 
icon picture locations to NSFU«.R«f vrences. 

• The desktop implementation calls Contain««.Getlmplementation, passing in the file 
type of the file and getting back the Containe«.lmplementation for that file type. 

• The desktop implementation calls the Contain««.PictureProc that is in the 
Implementation; (that is, impi.pictureProc), passing in: 

• data : the NSFiie.Ref erence for the file 

• old: normal 

• new: highlighted 

• The application's PictureProc displays a highlighted version of its icon picture, perhaps 
simply calling Display. In vert. 

• When the mouse button goes up (a "PointUp" atom), the desktop implementation 
becomes the current selection manager by calling Selection. Set. It sets the desktop 
window to be the current input focus by calling Tlp.SetlnputFocus. Setting the input 
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focus to be the desktop window ensures that keys such as OPEN, PROPS, COPY,and so 
forth, will all go to the desktop's NotifyProc. 

END. 



3.3.2 PROPS of an Icon 

Assume an icon on the desktop is selected. The user presses PROPS. After changing some 
items in the property sheet, the user selects Done. 

• The desktop implementation's TiP.NotifyProc gets the notification (a '*PropsDown" 
atom) and determines which icon picture is currently selected and what file is 
represented by that icon picture. 

• The desktop implementation calls Containee.Getlmplementation, passing in the file 
type of the file and getting back the Containe«.lmpiementation for that file type. 

• The desktop implementation calls the Containee.GenericProc that is in the 
Impiementation; (that is, impi.genericProc), passing in: 

• data: the NSFti«. Reference for the file 

• atom: "Props" 

• changeProc: a Containe«.ChangeProc that belongs to the desktop implementation 

• changeProcData: a pointer to some desktop implementation data that identifies jpai^ 
the icon/file being operated on. 

• The application's GenericProc creates a property sheet by calling PropertySheet.Create. It 
probably also opens and retrieves some data out of the file (using various NSFiie 
operations) and uses that data to set the initial values of the items in the property 
sheet. 

• Typically, the client wants to save the NSFil«,Handle for the file while the property sheet 
is open. In addition, if the opening and closing of the property sheet might cause the 
file's attributes to change, the application's GenericProc must save the passed 
changeProc and changeProcOata. A typical example is when the file's name is one of 
the items in the property sheet and the user can change the name. The data is saved by 
allocating a record with this data in it and passing a pointer to the record as the 
clIentData parameter to PropertySheet.Create. Later, when the user selects Done or 
Apply, this data may be recovered (see the rest of this flow description). Note: This 
data cannot be saved in a local frame (such as that of the GenericProc) because the 
GenericProc must return to the notifier after creating the property sheet; when the 
user selects Done or Apply that is a new call stack. The client data should not be saved 
in a global frame because more than one property sheet may be open for a particular 
application. 

• The application's GenericProc returns the starWindowShell.Handle for the property sheet. 

• The desktop implementation displays the property sheet by calling jlllis, 
StarWindowShell.Push; then the desktop's NotifyProc returns to the Notifier. ' 
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• The user changes some items and then selects Done. 

• The PropertySheet implementation calls the client's Prop«rtySheet.MenultemProc that 
was passed in to PropertyShe«t.Create, passing in: 

• shell : the StarWindowShell for the property sheet 

• formWindow: the FormWlndow for the property sheet 

• menultem: done 

• clientData: the pointer to the client's data that was passed to Prop«rtySheet.Create. 

• The client's MenultemProc recovers the client's data (the file handle, the changeProc 
and changeProcOata, and any other relevant client data) from the clientOata 
parameter. It determines if the user made any changes and, if so, updates the file 
accordingly and calls the changeProc, passing in the changeProcData, the file 
reference, and a list of the changed file attributes. 

• The desktop's ChangeProc causes the icon picture to be redisplayed, because changing 
an attribute such as the name requires the picture to be updated with the new name. 

• The client's MenultemProc returns to the PropertySheet implementation, indicating 
that the property sheet should be destroyed. 

• The PropertySheet implementation destroys the property sheet by calling 
StarWindowSh«il.Pop and returns to the Notifler. 

• END. 

3.3.3 OPEN an Icon 

Opening an icon is similar to opening a property sheet for an icon. 

3.3.4 COPY Something to an Icon 

Assume something has been selected. The user presses COPY and then points at an icon. 

• When the user presses COPY, the NotifyProc for the window that currently has the 
input focus (and the selection) is called. It calls TiPStar.SetMode [copy] to set the 
environment into copy mode and then returns to the Notifler. It might also call 
Cursor.Set to change the cursor shape to indicate move mode. 

• SetMode replaces the NormatMous«.TIP table with the CopyMod«Mouse.T1P table. 

• The user presses the mouse button down over an icon on the desktop. 

• The desktop's NotifyProc gets called with a ''Copy Mode Down" atom (instead of a 
"PointDown" atom because of the TIP table switch). It determines what file is 
represented by the icon picture the user is pointing at. It calls 
Containee.Getlmplementation, passing in the file's type and getting back a 
Contain««.lmplementation. It calls the Implementation's GenericProc passing in: 

• data : the NSFUe.Ref erence for the file 
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• atom: "CanYouTake" 

The application's GenericProc calls Seiaction.CanYouConvert or Selection. HowHard to 
determine if the current selection can be converted to target type(s) that the 
application can take. For example, if the icon being copied to is a printer icon, it calls 
HowHard with targets of interpressMaster and file. 

The Selection implementation calls the current selection manager's 
S«ie€tion.ConvertProc. It returns an indication of how hard it would be to convert the 
selection to the given target types. 

The application's GenericProc returns a pointer to true if it determines that it can take 
the current selection and false if it cannot. 

The desktop implementation changes the cursor shape to a question mark if the 
application's GenericProc returns false. Otherwise, it leaves the cursor as it was. 

The user releases the mouse button. 

The desktop's NotifyProc gets called with a '*CopyModeUp" atom. It determines what 
file is represented by the icon picture the user is pointing at. It calls 
Contain««.Getlmplementation, passing in the file's type and getting back a 
Containee.lmplementation. It then calls the implementation's GenericProc, passing in: 

• data: the NSFiie.Reference for the file 

• atom: "TakeSelectionCopy" 

• changeProc: a ContaineeXhangeProc that belongs to the desktop implementation 

• changeProcOata: a pointer to some desktop implementation data that identifies 
the icon/file being copied to 



• The application's GenericProc calls Selection.Convert or (Selection.Enumerate) to convert 
the selection to the desired type. The application then operates on the converted 
selection value as appropriate for that application. For example, the printer icon 
application converts the selection to an interpressMaster and sends the master to the 
printer. (See the Selection chapter for a full flow description of the selection 
mechanism.) 

• The application's GenericProc returns to the desktop's NotifyProc, which returns to the 
Notifier. 



• END. 



3.4 Programming Conventions 

The ViewPoint environment assumes that the programs that run in it are friendly and that 
they are not trying to circumvent or sabotage the system. The system does not enforce 
many of the conventions described here but assumes that application programmers will 
adhere to them voluntarily. If these conventions are not followed, the ViewPoint 
environment may degrade or break down altogether. 
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The most important principle is that users should have complete control over their 
environment. In particular, clients shall not pre-empt users. A user should never be forced 
by a client into a situation where the only thing that can be done is to interact with only 
one application. Furthermore, the client should avoid falling into a particular mode when 
interacting with the user; that is, an application should avoid imposing unnecessary 
restrictions on the sequence of user actions. 

This goal of user control has implications for the designs of applications. A client should 
never seize control of the processor while getting user input. This tends to happen when the 
client wants to use the ''get a command from the user and execute it** mode of operation. 
Instead, an application should arrange for Viewpoint to notify it when the user wishes to 
communicate some event to the application. This is known as the "Don't call us, we'll call 
you" principle. 

The user owns the window layout on the screen. Although the client can rearrange the 
windows, this is discouraged. Users have particular and differing tastes in the way they 
wish to lay out windows on the display; it is not the client's role to override the user's 
decisions. In particular, clients should avoid making windows jump up and down to try to 
capture the user's attention. If the user has put a window off to the side, then he does not 
want to be bothered by it. 

3.4.1 Notifier 

Viewpoint sends most user input actions to the window that has set itself to be the focus for 
user input; the rest of the actions are directed to the window containing the cursor. (See the 
TIP interface for details on how the decision is made where to send these actions.) A process 
in ViewPoint notes all user input actions and determines which window should receive 
each one. A client is concerned only with the actions that are directed to its window; it need 
not concern itself with determining which actions are intended for it. 

The basic notification mechanism directs user input to one of many windows in the window 
tree. Each window has a TlP.Table and a TIP.NotifyProc. The table is a structure that 
translates a sequence of user actions into a sequence of results that are then passed to the 
notify procedure of the window. 

There are two processes that share the notification responsibilities, the Stimulus process 
and the Notifier process. The Stimulus process is a high-priority process that wakes up 
approximately 50 times a second. When it runs, it makes the cursor follow the mouse and 
watches for keyboard keys going up or down, mouse motion, and mouse buttons going up or 
down, enqueuing these events for the Notifier process. 

The Notifier process dequeues these events, determines which window the event is for, and 
tries to match the events in the window's table. If it finds a match in the table, it calls the 
window's notify procedure with the results specified in the table. If no match is found, it 
tries the next table in the window's chain of tables. If no match is found in any table, the 
event is discarded. 

The Notifier process is important. To avoid multi-process interference, some operations in 
the system can happen only in the Notifier process. Setting the selection is one such 
operation,. The Notifier process is also the one most closely tied to the user. The Notifier 
waits until a NotifyProc finishes for one user action before processing the next user action. 
If an operation takes an extended time to complete (more than three to five seconds), it 
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should be forked from the Notifier process to run in a separate process so that the Notiiier 
process is free to respond to the user's actions. Of course, the application writer must take 
great care when stepping into this world of parallel processing. 

3.4.2 Multiple Processes, lyiultiple Instances 

In ViewPoint, many programs can run simultaneously. The designer of a client-callable 
package should bear in mind that several different asynchronous clients may invoke his 
package, so the package should be monitored. 

The simplest design is to have a single entry procedure that all clients must call. While one 
client is using the package, all other clients block on the monitor lock. Of course, no state 
should be maintained internally between successive calls to the package, because there is 
no guarantee that the same client is calling each time. 

This simple approach has the disadvantage that clients are simply stopped for what may be 
a long time, with no option of taking alternate action. To ease this restriction, the entry 
procedure can check a "busy" bit in the package. If the package is busy, the procedure can 
return this result to the client. The client can then decide whether to give up, try 
something else, or try again. This is less likely to tie up an application for a long period, 
and the user can use the application for other purposes. . 

If the package is providing a collection of procedures and cannot provide its services in a 
single procedure, the package and its clients must pass state back and forth in the form of 
an object. The package can use a single monitor on its code to protect the object, or it can jan^ 
provide a monitor as part of each object. If it does the latter, then several clients can be 
executing safely at the same time. 

Some packages require that a client provide procedures that are called by the package. The 
designer of such a package should have these client-provided procedures take an extra 
parameter, a long pointer to client Instance data. When the client provides the package 
with the procedures, it also provides the instance data to pass to the procedures when they 
are called. The client can then use this instance data to distinguish between several 
different instances of itself that are sharing the same code. 

3.4.3 Resource Management 

Programs in the Xerox Development Environment must explicitly manage resources. For 
example, memory is explicitly allocated and deallocated by programs; there is no garbage 
collector to reclaim unused memory. All programs share the same pool of resources, and 
there is no scheduler watching for programs using more than their share of execution time, 
memory, or any other resource. 

Programs must manage resources carefully. If a program does not return a resource when 
it is done with it, that resource will never become avadlable to any other program and the 
performance of the environment will degrade. The most common resource, and one of the 
more di^cult to manage, is memory. 

When interfaces exchange resources, clients must be very careful about who is responsible 
for the resource. The program that is responsible for the deallocation of a resource is the 
owner of that resource. One example of a resource is a file handle. If a program passes a 
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file handle to another program, both programs must agree about who owns that file handle. 
J Did the caller transfer ownership by passing the file handle, or is it retaining ownership 

and only letting the called procedure use the file handle? If there is disagreement between 
the two programs, either the file will be released twice, or it will never be released at all. 
All interfaces involving resources must state explicitly whether ownership is transferred. 
To ease the problem of memory management when the ownership of memory can change, a 
heap called the system heap is used in ViewPoint. If a piece of memory can have its 
ownership transferred, it is either allocated from the system heap or a deallocation 
procedure must be provided for it. 

The most common resource appearing in interfaces is an XString (Reader or ReaderBody). 

There must be agreement about which program is responsible for deallocating the string's 
bytes. Typically, a string passed as an input parameter does not carry ownership with it; 
implementors of such procedures should not deallocate or change the string. If it is 
necessary for the implementor to modify the string or use it after the procedure returns, 
the implementor should first copy it. Clients should be particularly careful when a 
procedure returns a string to note whether ownership has come with it. 

3.4.4 Stopping Applications 

The ViewPoint environment consists of cooperating processes. There are no facilities for 
cleanly terminating an arbitrary collection of processes. It is assumed that application 
writers are good citizens and will design their tools to stop voluntarily when asked to stop. 

An application should stop Lf the user aborts the application. There are two ways to 
^^"^ determine if the user has aborted an application. (1) An application's window can have a 

TlP.AttentionProc that is called as soon as the user presses the STOP key. (2) Procedures in 
the TIP interface can check whether a user has aborted an application with the STOP key in 
the application's window. An application should check for a user abort at frequent 
intervals and be prepared to stop executing and clean up after itself. Because the 
application controls when it checks, it can check at points in its execution when its state is 
easy to clean up. Packages that can be called from several programs should take a 
procedure parameter that can be called to see whether the user has aborted. 

3.4.5 Multinationality 

ViewPoint is designed to support easy transport of applications to other countries. The 
string package (XString, XChar, XFormat, and so forth) supports the Xerox Character Code 
Standard^ which allows for strings in many languages to be intermixed. The XMessage 
interface allows user messages to be translated into other languages because the 
application programmer can put all these messages into a module separate from the rest of 
the application code. The KeyboardKey interface supports the addition of keyboards for 
many languages. 

Application programmers are strongly encouraged to allow their application to be 
multilingual. This means for example, using XString for all string operations and using 
XMessage to manage any text that will be displayed to the user. It also means not making 
any language assumptions about characters received from the user. An application that 
'''^<m^ expects typing input from the user should be prepared to receive characters from any 

character set. 
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3.5 Summary of Interfaces 

Atom provides the mechanism for making TIP, Event, and Containee atoms. 
AtomicProf iie provides a mechanism for storing and retrieving global values. 
Attention provides a means of displaying messages to the user. 

BackgroundProcess provides basic user feedback and control facilities to clients that want 
to nm in a process other than the the Notifier process. 

BiackKeys provides the capability to change the interpretation of the central (black) section 
of the keyboard. 

Containee is an application registration facility. It allows an application to register its 
implementation for flies of a particular type. 

ContainerCache provides a simple cacheing mechanism for the implementor of a container 
source. 

ContainerSource defines the procedures that must be implemented to provide a source of 
items for a container window. 

ContainerWindow creates a window that displays an ordered list of items that behave like 
icons on a desktop. 

Context provides a mechanism for clients to associate data with windows. 

Cursor provides facilities for a client to manipulate the appearance of the cursor that 
represents the mouse position on the screen. 

Display provides facilities to display bits in windows. 

Event provides clients with the ability to be notified of events that take place 
asynchronously on a system-wide basis. 

FileContainerShelt creates a StarWindowSheli with a ContainerWindow as a body window 
that is backed by a FiieContainerSource. 

FiieContainerSource creates a container source that is backed by a file that has children. 

FormWindow creates a window with various types of form items in it, such as text, 
boolean, choice (enumerated), command, and window. FormWindow is used to create 
property sheets. 

FormWindowMessageParse provides procedures that parse strings to produce various 
FormWindow typ€s. 

IdleControi provides access to the basic controlling module of ViewPoint. 
KeyboardKey is a client keyboard (the central black keys) registration facility. 
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KeyboardWindow provides a particular implementation for a keyboard window. 
^"^^ Leveil VKeys defines the names of the physical keys. 

MenuOata allows menus and menu items to be created. 

Message Window provides a facility for posting messages in a window to the user . 

PopupMenu allows a menu to be displayed (popped up) anywhere on the screen. 

PropertySheet creates a property sheet. A property sheet shows the properties of some 
object to the user and allows the user to change the properties. 

Selection provides the facilities for a client to manipulate the user's current selection. It 
also provides procedures that enable someone other than the originator of the selection to 
request information relating to the selection and to negotiate for a copy of the selection in a 
particular format. 

SimpieTextOispiay provides facilities for displaying, measuring, and resolving strings of 
Xerox Character Code Standard text. It can handle only nonattributed single-font text. 

SimpieTextEdit provides facilities for presenting short, editable pieces of text to the user. 

SimpleTextFont provides access to the default system font that is used to display 
Viewpoint's text, such as the text in menus, the attention window, window names, 
containers, property sheet text items, and so forth. 

SoftKeys provides for client-defined function keys designated to be the isolated row of 
function keys at the top of the physical keyboard. 

StarOesktop provides access to the user's desktop file and window. 

StarWindowSheii provides facilities for creating Star-like windows. 

TIP provides basic user input facilities through a flexible mechanism that translates 
hardware level actions from the keyboard and mouse into higher-level client action 
requests. 

TlPStar provides access to Viewpoint's normal set of TIP tables. 

Undo provides facilities that allow an application to register undo opportunities, so that 
when the user requests that something be undone, the application is called to do so. 

Window defines the low-level window management package used by ViewPoint. 

XChar defines the basic character type as defined in the Xerox Character Code Standard as 
well as some operations on it. 

XCharSetNNN enumerates the character codes in character set NNN. 
"-^^0^ XCharSets enumerates the character sets defined in the Xerox Character Code Standard. 
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XComSoftMessage defines messages for some commonly used strings, such as Yes, No, 
day-of-the-week, month.and so forth. 

XFormat converts various types into XStrings. 

XLReai supports manipulation of real numbers with greater precision than Mesa reals. 

XMessage supports the multilingual requirements of systems that require the text 
displayed to the user be separable from the code and algorithms that use it. 

XString provides the basic data structures for representing encoded sequences of characters 
as defined in the Xerox Character Code Standard, It also provides several operations on 
these data structures. 

XTime provides facilities to acquire and edit times into XStrings and XStrings into times. 
XToken parses XStrings into other types 
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4.1 Overview 

AdjustableWindow makes an arbitrary window become shrinkable, growable, and/or 
moveable by the user. For a comprehensive overview of all the subwindow interfaces and 
their intended use, see the Subwindow Overview chapter. 

4.2 Interface Items 

4.2.1 Create Proc 

Create: procI 

window: window.Handle, 
adjustProc; AdjustProc. 
zone: UNCOUNTED ZONE. 

limitProc LimitProc 4-nil. 

adjustabieEdges: Edges «-defaultAdjustabieEdges. 
topBottom. move: boolean «- false. 

upperCornersCoior. iowerCornersColor: oispiay.Brick 4~nil- NIL means Gray-] 

Edge: type » {left, right top. bottom}.- 
Edges: type « packed array Edge of BooleanFaiseOefauit; 
BooleanFatseOefauit: TYPE » boolean 4~ false. - 
defaultAdjustableEdges: Edges a [ 

left: FALSE, Hght: TRUE, tOp: FALSE. bOttOm: TRUE); 

Create makes window resizeable, moveable and/or top/bottomable. adjustabieEdges 

governs which edges or corners can be adjusted. defaultAdjustableEdges, for e.xample, 
means the lower right corner of window is adjustable (which means that the upper left 
corner is fixed). If only bottom is TRUE the only possible resize is a "drag" of the bottom edge 
of the window. The window is moveable If move is TRUE and top/bottomable if topSottom 
is TRUE. upperCornersCoior and IowerCornersColor allow the client to specify white or 
gray etc. for the adjustable quadrants. adjustProc and limitProc are the adjust and limit 
procs for window. 
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4.2.2 Adjust and Limit Procs 

AdjuStPrOCTYPE a PROCEDURE I 

window: Window. Handle, 
box: Window.BOX. 

when: Whenl; 
When: TYPE a {before, after}; 

An AdjustProc is the proc that is called when window's box is changing. It will be called 
both before and after the Window.SlideAndSize occurs. 

GetAdjustProc: PROClwindow: window.Handle] 
RETURNS [AdjustProc]: 

Get the AdjustProc associated with window. 

SetAd j ustProc: proc [ 

window: Window.Handle. 

proc; AdjustProcl 
returns [old: AdjustProc]; 

Set the AdjustProc for window to be proc. Returns the previously set AdjustProc. 

LimitProc:TYPE » procedure I 
window: Window.Handle, 

box: Window.BOX] 
RETURNS [newBOX: Window.BOX]: 

A LimitProc is the proc that is called when window box is about to change. It allows the 
client a chance to disallow (newBox «(- oldBox) or modify (newBox otherBox) the 
proposed new box value before the call to Window.SlideAndSize occurs. 

GetLimitProc: proc [window: Window.Handle] 
RETURNS [LimitProc]; 

Get the LimitProc associated with window. 

SetLimitProc: proc[ 

window: Window.Handle, 

proc: LimitProc] 
RETURNS (old: LimitProc]; 

Set the LimitProc for window to be proc. Returns the previously set LimitProc. 

4.2.3 Utilities 

ISit: PROCEDURE [windOW: Window.Handle] RETURNS [yeS: BOOLEAN]; 

Returns true if window is an adjustable window. 
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GetZone: PROCEDURE(window: window.Handle] returns [zone: uncounted zone]; 
Returns the zone associated with window. 

4.2.4 Friends 

CailAncestorForTheseCorners: procedure [ 
window: window.Handle. 
corners: Corners 4- all [false]]: 

Corner: type « {upperLeft. upperRight. lowerLeft, lowerRight}: 
Corners: TYPE « packed array Corner of BooieanFaiseOefauit; 

CailAncestorForTheseCorners should be called if the client wishes parent windows to 
receive notifications (like the shell being notified when adjustments are made to the 
bottom subwindow in a subdivided shell). For example, a subwindow can be designed to fill 
the lower segment of a shell and it's lower grabbers to cause the shell to resize as well as 
the subwindow. SubwindowManager uses this technique. 

4.2.3 Errors 

Error: error [type: ErrorTypej; 

ErrorType: type a {notAnAdjustableWlndow. notAl lowed}; 

4.3 Usage/Examples 

--from SubwindowManager.MakeSW 

-make the new sw adjustable and set the manager procs 

AdjustabieWindow.Create[sw, CoordlnateSWAdjusts, zone, 

CoordinateSWLimits, [FALSE.FALSE.horizAd]ust,vertAd]ustl. false, false]; 

AdjustabieWindow.CailAncestorForTheseCorners[ 

sw, [FALSEJ=ALSEJRUE,TRUE]1; 

IF SubwindowFriends.GetSWProcs(typ€].scrollSWProc # nil then 
sw 4- SubwindowFriends.GetSWProcs(type].scrollSWProc[ 
sw, vertScrollbar, horizScrollbar]; 
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4.4 Index of Interface Items 



Item 

AdjustProc: TYPE 
BooleanFalseDefault: type 



Page 
2 
1 



CallAncestorForThese Coraers: procedure 3 



Create: procedure 1 

defaultAdjustableEdges: Edges 1 

Edge: type 1 

Edges: TYPE 1 

Error 3 

ErrorType: type 3 

GetAdjustProc: procedure 2 

GetLimitProc: procedure 2 

GetZone: procedure 3 

lslt:PROCEDURE 2 

LimitProc: type 2 

SetAdjustProc: procedure 2 

SetLimitProc: procedure 2 

When: type 2 



Corner: type 
Comers: type 
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5.1 Overview 

ApplicationFolder provides access to the folder that contains all the component files of an 
application. A full application is composed of one or more beds, a message file, a description 
file, and other data flies such as .TIP or .Icons. These components are all put together into a 
folder with a specific file type, called an Application (or ApplicationFolder). 

When the application is loaded and started, one of the first things it does is get its data 
files. The actual file names of the data flies are usually specified in the application's 
description file, which is a file that may be read using the OptionFile interface. The 
application gets its data files by using Applicationfolder.FromName to obtain the 
ApplicationFolder file, using ApplicationFolder. FindDescriptionFile to get the description file 
from the ApplicationFolder file, and then using OptionFile.GetString Value to get the data 
files names. (See Usage/Examples.) ApplicationFolderExtra.lnitMessages makes 
initializing messages much easier, just pass in an internal name and get back an 
XMessage.Handle. No more looking for description file, finding the message file, etc. 

5.2 Interface Items 

FromName: procedure [internalName: xstring. Reader] 
RETURNS [applicationFolder: NSFii«.Reference]; 

Returns the folder for the given application. internalName is the section name in the 
description file. Returns NSFiie.nui I Reference if not found. 

FindDescriptionFile: procedure [applicationFolder: NSFite.Handle] 
RETURNS [descriptionFile: NSFiie.Reference]; 

Finds a file with file type = OptionFile (4385) in the applicationFolder. Returns 
NSFiie.nullReference If not found. 

FindDescriptionFileX: procedure [applicationFolder: NSFii«.Handle, session: NSFii«.Session] 
RETURNS [descriptionFile: NSFtie.Reference]; 
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Finds a file with file type = OptionFile (4385) in the applicationFolder using the specified 
NSFiie.Session, Returns NSFiie.nullReference if not found. Fine Point: in BWS4.3, this is in 
ApplicationFolderEztra.mesa. 

EventOata: TYPE > record [ 

applicationFolder: NSFii«.Reference, 

internalName: xstnng.Reader, 
applicationADF: NSFile.Reference, 
containsFontFlle: BOOLEAN, 
versionStamp: CARDINAL, 
priority: CARDINAL]; 

versionStamp: CARDINAL a 2; 

The application loader notifies the AppllcationLoaded event after loading and starting an 
application. EventData is passed as Event.EventData for this event. applicationADF is the 
description file, containsFontFile is TRUE if it contains NovaFontFile entry in the 
description file. The current versionStamp is 2. If the versionStamp is 2, then the priority 
is cached as an extended attribute of the application folder. The value of priority of an 
application folder is specified in the ADF's priority entry. At startup time, tlie autorun 
applications are started in the order of ascending priority number. Fine Point: in BWS4.3. 

EventOata is in ApplicationFolderExtra2.mesa. 

The application loader also notifies the following events: 

AboutLoading: Notifies when the loader try to load an application. 

LoadVetoed: Notifies when loading vetoed by the client of the AboutLoading event. 

LoadedAndAboutToStart: Notifies when finished loading an application. 

InitMessages: procedure [internalName: xstring.Reader, label : xstring. Reader ^ nil, 
domainindex: cardinal <-0] returns [h: xMessage.Handte] ; 

Returns initialized XMessage.Handle for the specified application folder, internalName is 
the section name in the description file. If label is non-NIL, then label is used as the entry 
name in the description file. If label is NIL, then the entry MessageFile is used, 
domainindex is XM«ssage.MsgDomainS. Fine Point: In BWS4.3, this is in ApplicationFolderExtra.mesa. 

5.3 Usage/Examples 

This example code obtains the message file. 
— File: SsmpleMsgFUelnitlmpimesa - last edit: 

Copyright (C) 1985 by Xerox Corporation, Ail rights reserved. 
DIRECTORY 

ApplicationFolder using [FindOescriptionFile, FromName], 
Heap USING [systemZone], 

NSFile USING [Close, Error, GetReference, Handle, nullHandle, nullReference, OpenByNani((lill|| 
OpenByReference, Reference, Type], 
NSString using [FreeString, String], 
OptionFile using [GetStringValue], 
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SampleBWSAppiicationOps, 

XMessage using [ClientOata, FreeMsgOomainsStorage, Handle, MessagesFromRef erence, 
MsgDomains], 

XString using [FromSTRING, NSStringFromReader, Reader, ReaderBody]; 

SampieMsgFilelmpl: program 

IMPORTS ApplicationFoider, Heap, NSFiie, NSString, OptionFile, XMessage, XString 
EXPORTS SampieBWSApplicationOps « { 

— Data 

h: XMessage.Handle 4- nil; 

iocalZone: uncounted zone *- Heap.systemZone; 

" Procedures 

DeleteMessages: procedure [clientData: XMessage.CIientOata] » {}; 

GetMessageHandie: public procedure returns [XMessage.Handle] a {RETURN[h]}; 

InitMessages: procedure * { 

internaiName: xstnng.ReaderBody <~xstring.FromSTRiNG ['*SampieBWSApplication"L]; 
msgOonnains: XMessage.MsgOomains nil; 
msgDomains <~ XMessage. MessagesFromReference [ 

file: GetMessageFileRef [AppikationFoider.FromName [©internaiName]], 

dientOata: nil, 

proc: DeleteMessages ]; 
h 4- msgDomains[0].handle; 
XMessage.FreeMsgOomainsStorage [msgDomains]; 

}; 

GetMessageFileRef: procedure [folder: NSFiie.Reference] 

RETURNS [msgFiie: NSFiie.Reference ♦-NSFiie.nullReference] ■ { 

folderHandle: NSFiie.Handle ^NSFUe.OpenByReference [folder]; 

internaiName: xstring.ReaderBody ♦-xstring.FromsTRiNG ["SampleBWSApplication"L]; 

messageFile: xstring.ReaderBody ^-xstring.FromsTRiNG ['*MessageFile"L]; 

FindMessageFiieFromName: PROCEDURE [value: xstring.Reader] a { 

nssName: NSStnng.String <-xstring.NSStringFromReader [r: value, z: IocalZone]; 
msgFileHandle: NSFiie.Handle NSFiie.nullHandie; 

msgFileHandle «-NSFiie.OpenByName [directory: folderHandle, path: nssName ! 

NSFUe.Error ■ > {msgFileHandle <-NSFiie.nullHandle; continue}]; 
IF msgFileHandle » NSFiie.nullHandle then error; — no message file! 
msgFile <<- NSFiie.GetReference [msgFileHandle]; 
NSFiie.Close [msgFileHandle]; 
NSString.FreeString [z: IocalZone, s: nssName]; 

}; 

OptionFHe.GetStringValue [section: ©internaiName, entry: ©messageFile, 
callBack: FindMessageFiieFromName, 
file: AppiicationFoider.FindDescriptionFile [folderHandle]]; 
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NSFiie.Ciose [folderHandie]; 

}; 

" Mainline code 
InitMessagesQ; 
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5.4 Index of Interface Items 



Item Page 

EventData: type 1 

FindDescriptionFiie: procedure 1 

FlndDescriptionFileX: procedure 1 

FromName: procedure 1 

InitMessages: procedure 2 

versionStamp: CARDINAL 2 



ApplicationFolder 
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6.1 Overview 

Although it is often convenient to name an object using a textual name, XStrings are 
somewhat clumsy to compare and pass around. An atom is a one-word datum that has a 
one-to-one correspondence with a textual name. Using atoms, objects may be named 
textually without ha\ring to store, copy, Euid compare the strings themselves. Atoms were 
made popular by the Lisp language. 

The textual name associated with an atom is called its PName, just as it is in Lisp. If two 
atoms are equal, they correspond to the same PName and vice versa. An atom may also 
have properties associated with it; a property is a [name, value] pair. 

6.2 Interface Items 

6.2.1 Making Atoms 

AT0M:type[11; 

null: ATOM « loophol£[0]. 

An ATOM is a one-word datum that has a one-to-one correspondence with a textual name, 
or PName. If two ATOMs are equal, they correspond to the same pName. If two pNames are 
equal, they correspond to the same ATOM. 

Make: procedure [pName: xstnng.Reacier] returns [atom: ATOM]; 

MakeAtom: procedure [pName: long string] returns [atom: ATOM]; 

MakeAtom and Make return the ATOM corresponding to pName, creating one if 
necessary. In pName, uppercase and lowercase characters are different and result in 
different ATOMs. The atom returned is valid for the duration of the boot session, and the 
pName is rememberedfor the duration of the boot session. 

GetPName: procedure [atom: ATOM] returns [pName: xstring.Reader]; 
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GetPName returns the name of atom, returning nil Lf atom is null. It raises the error 
NoSuchAtom if atom is not valid. 

6.2.2 Error 

NoSuchAtom: error; 

NoSuchAtom may be raised by GetPName, PutProp, GetProp, or RemoveProp. It is raised 
when an operation is presented with an ATOM for which no Make or MakeAtom operation 
has been done in the boot session. Such atoms are called invalid atoms. 

6.2.3 Property Lists 

Pair: type » record [prop: ATOM, value: RefAny]; 

Ref Any: TYPE ■ long pointer; 

RefPair:TYPE « long pointer to readonly Pair; 

Pair defines the [name, value] pair for a property. Properties are named by atoms and have 
long pointers as values. Property pairs are referenced by a read-only pointer. 

PutProp: PROCEDURE [onto: ATOM, pair: Pair]; 

PutProp adds a property psdr to onto. If the property already exists, the value is updated. If 
onto is null, no action takes place. PutProp raises the error NoSuchAtom if onto is not 
valid. * 

GetProp: procedure [onto, prop: ATOM] returns [pair: RefPair]; 

GetProp returns the property pair whose property name is the atom prop from atom onto. 
If onto does not have a property whose name is prop or onto is null, nil is returned. 
GetProp raises the error NoSuchAtom if onto is not valid. Note: The client may not change 
the property pair. 

RemoveProp: procedure [onto, prop: ATOM]; 

RemoveProp removes the property pair whose property name is the atom prop from atom 
onto. If onto is null, no action takes place. RemoveProp raises the error NoSuchAtom if 
onto is not valid. 

6.2.4 Enumerating Atoms and Property Lists 

MapAtomProc: type a procedure [ATOM] returns [boolean]; 

MapAtomProc is used by MapAtom to enumerate atoms. When it returns true, the 
enumeration stops. 

MapAtoms: procedure [proc: MapAtomProc] returns [lastAtom: ATOM]; 
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MapAtoms enumerates the atoms, calling proc once for each atom. If proc returns true, 
MapAtoms returns that atom. If proc never returns true, MapAtoms returns null. 

MapPListProc: type ■ procedure [RefPaIr] returns [boolean]; 

MapPListProc is used by MapPList to enumerate property lists. When it returns true, the 
enumeration stops. Note: The client may not change the property pair. 

MapPList: procedure [atom: ATOM, proc: MapPListProc] returns [iastPair: RefPair]; 

MapPList enumerates the property list of atom, calling proc once for each pair. If proc 
returns true, MapPList returns that pair. If proc never returns true, MapPList returns nil. 

6.3 Usage/Examples 

Atom is most appropriately used for communicating names and permanent data between 
separate applications or between far-flung parts of a single application. The AtomicProfile 
interface is an example of this use. 

However, ATOMs and atom property lists add to the working set of every application, and 
thus degrade system performance as a whole. This happens because Atom must make a 
copy of the atom name in its (permanent) database, and every client of Atom uses that 
database. It is much better to keep an application's data separated from other data. 

Property lists are a shared, global resource and should be used for sharing other global 
resources. They should not be used for transient data. For example, consider the chaos that 
would ensue if several instances of an application were running simultaneously and each 
assumed that the property list of a particular atom was its to read and write. (Of course, 
this interference could also result from different applications running at different times.) 

ATOMs take a significant amount of time to create. Applications interested in good 
performance will only use ATOMs if they need a runtime-extendable enumeration; a 
simple compile-time enumeration is much more efficient. 

If you want an atom with a property list for a private or transient usage (a bad idea in any 
case) you must make sure that the atom is unique, so as not to interfere with other 
applications using the same atom. Code such as 

myList: Atom.ATOM ■ Atom.MakeAtom["string lisfLJ; - WRONG 

must be replaced by code that gives an atom name that is unique to the application or 
module (or instance, if multiple instances may be running). 

Two of the major uses of atoms are in the Event and TIP interfaces. In the Event interface, 
atoms name events. In the TIP interface they are used in TIP tables and TIP results to name 
actions. (See those interfaces for more information.) 



Atom 



The names of atoms are case sensitive. For example, atom1 and atom2 are not equal, while 
atom1 and atom3 are equal. 

atom1:ATOM « MakeAtom[''Atom"Ll; 
atom2: ATOM « MakeAtoml''ATOM"L]; 
atom3:ATOM « Make[GetPName{atom1]]; 

The value of an atom is a function of the characters of its name and the names of the atoms 
that have been previously created. Atoms may not be pickled (put in a permanent 
representation that may be filed and recovered later) or transmitted to another system. 
The atom is just a convenient way to represent and manipulate the name, which is the 
permanent representation. 
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6.4 Index of Interface Items 
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ATOM: TYPE 
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GetPName: procedure 
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NoSuchAtom: error 


2 


null: ATOM 


1 


Pair: type 


2 


PutProp: PROCEDURE 


2 


Ref Any: type 


2 


RefPair: type 


2 


RemoveProp: procedure 


2 



Atom 



6-6 



AtomicProfile 



7.1 Overview 

The AtomicProfile interface provides a general mechanism for storing and retrieving 
global values, such as user name and password. Values are named by atoms and may have 
a type of either boolean, long integer, or string. Only one value is associated with each 
atom, regardless of type. 

Boolean and long integer values are simple values, unlike string values, which are passed 
by reference. The value of strings may be gotten by calling the GetStrIng routine, in which 
case they must be returned to the implementation using DoneWithString. They may be 
gotten by using a callback procedure in EnumerateString. 

7.2 Interface Items 

7.2.1 Boolean Values 

GetBOOLEAN: procedure [atom: Atom.ATOM] returns [boolean]; 

GetBOOLEAN returns the boolean value associated with atom. If no boolean value is 
associated with atom, GetBOOLEAN returns false. 

SetBOOLEAN: procedure [atom: Atom.ATOM, boolean: boolean]; 

SetBOOLEAN associates the boolean value boolean with atom. If atom previously had 
another value associated with it, that value is replaced. The event AtomicProflleChange is 
notified, with event data being a long pointer to atom. 

7.2.2 Integer Values 

GetLONGiNTEGER: procedure [atom: Atom.ATOM] returns [long integer]; 

GetLONGINTEGER returns the long integer value associated with atom. If no long integer 
value is associated with atom, GetLONGINTEGER returns 0. 
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SetLONGlNTEGER: procedure [atom: Atom.ATOM, int: long integer ]; 

SetLONGlNTEGER associates the long integer value int with atom. If atom previously had 
another value associated with it, that value is replaced. The event AtomicProfileChange is 
noti&ed, with event data being a long pointer to atom. 

7^3 String Values 

GetString: procedure [atom: Atom.ATOM] returns [ xstring.Reader]; 

GetString returns the string value associated with atom. The string is reference-counted, 
and the client must return the string by calling DoneWithString. If there is no string value 
associated with atom, GetString returns nil. 

DoneWithString: procedure [string: xstring.Reader]; 

A reader obtained by using GetString must be returned via DoneWithString so that the 
implementation's use-count will be correct. Failure to do so results in a storage leak if the 
value of the atom is replaced (see the example below). 

EnumerateString: procedure [ 
atom: Atoni.ATOM, proc: procedure [xstnng.Reader]]; 

EnumerateString provides an alternate method of examining the string value of an atom. If 
atom has a string value,, proc is called with the string value, proc is called from within the 
monitor of the Implementation. The reader is valid for the duration of the callback, but 
proc must not call any of the operations in the implementation. If atom has no string 
value, proc is not called. 

SetString: procedure [atom: Atom.ATOM, string: xstring.Reader, 
immutable: boolean «-> false ]; 

SetString associates the string value string with atom. If atom previously had another 
value associated with it, that value is replaced. If Immutable is false, SetString copies 
string's body and byte sequence; otherwise, it only copies the reader body. The client must 
not deallocate the byte sequence in this case. The event AtomicProfileChange is notified, 
with event data being a long pointer to atom. 

7.3 Usage/Examples 

AtomicProfile provides a general mechanism for storing and retrieving values. Actual use 
by a client depends on knowing the names and expected types of values. ViewPoint defines 
some basic values, such as user name and password. Other systems may define other 
values. 

In the following example, a client keeps track of the user name, which depends on the 
AtomicProfileChange event. UserNameChanged is called when any AtomicProfile value is 
changed. By examining the event data of the agent procedure, the example can act on 
changes to the user name. jlli 
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atomicProfileChange: Atom-ATOM a Atom.MakeAtom["AtomicProfileChange"L]; 
fullUserName: Atom-ATOM a Atom.MakeAtom["Fu!IUserName"L]; 
debugging: Atom^TOM ■ Atoni.MakeAtom[''Debugging"L]; 

UserNameChanged: EveirtJ^gentProc ■ { 

atomChanged: LONG POINTER TO Atom^TOM ■ eventOata; 
IF atomChanged f a fuiiUserName then { 
name: xstrtng.Reader ■ GetString[fullUserName]; 
< < do processing of new nanrte > > 

IF GetBOOLEAN[debugging] then {< < do debugging only code> >}; 
DoneWlthStringlname]}}; 

Ev«nt^ddDependency[ 

agent: UserNameChanged, myOata: nil, event: atomicProfileChange]; 
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7.4 Index of Interface Items 



Item Page 

Done With String: procedure 2 

EnumerateString: procedure 2 

GetBOOLEAN: procedure 1 

GetLONGlNTEaER: procedure 1 

GetString: procedure 2 

SetBOOLEAN: procedure 1 

SetLONGlNTEGER: procedure 2 

SetString: procedure 2 
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8.1 Overview 



The Attention interface provides a means for displaying messages to the user. It 
implements a single window into which messages are displayed. In addition to displaying 
messages, the Attention window has a menu to which clients can add system-wide 
commands. 

There are three types of messages: simple messages, sticky messages, and confirmed 
messages. Simple messages have no special semantics. Sticky messages are redisplayed 
when a non-sticky message is cleared. Attention keeps track of one sticky message. 
Confirmed messages ask for confirmation by the user. 

Attention allows messages to be logically appended. Each of the posting operations, Post, 
PostSticky, and PostAndConfi rm, contains a boolean parameter clear. If clear is true, the 
window is cleared before the message is displayed. If not, the message is appended to the 
currently displayed message. This allows the client to use Attention to construct complex 
messages. 

Note that Attention works in concert with BackgroundProcess. If Attention is called from 
the Notifier process, the message is posted immediately in the attention window. If 
Attention is called from a non-Notifier process that has registered itself with the 
background manager by calling BackgroundProcess. ManageMe, then the background 
manager intercepts these messages and allows the user to see them later upon request (see 
BackgroundProcess for more details). This means that Attention can be called from any 
process at any time without worry. Fins point: In ViewPoint 1.0, thers was no background manager and 
the following restriction applied: The Attention interface could only be called from the Notiiler process. 

To facilitate message construction, an XFormat.Handle is provided whose format procedure 
will post a simple message without clearing the window. See the example below and the 
XFormat chapter for more information. 

The Attention window has a global system menu. Operations are provided so that clients 
may add menu items to this menu, remove items from the menu, or swap items in the 
menu. 
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8.2 Interface Items 




8.2.1 Simple Messages 



Post: PROCEDURE [s: xstring.Reader, clear: boolean true, beep: boolean <- false, 
blink: boolean 4- false]; 

Post displays the message s in the Attention window. If clear is true, it clears the Attention 

window before displaying s; otherwise, it displays s after whatever text is currently 
showing. Attention makes its own copy of the reader body and bytes of s. beep and blink 
stipulate that the corresponding feedback be presented to the user. 

Clear: procedure; 

Clear clears the Attention window of any simple message. If a simple message is being 
displayed and there is a current sticky message, the sticky message is displayed. Clear has 
no effect if a sticky message is being displayed. 

formatHandle: xFormat. Handle; 

formatHandle is an XFormat.Handle provided by the Attention window that clients can use 
to post simple messages. Its format procedure logically calls Post with clear being false. 
(See below for an example.) 



Sticky messages are redisplayed when a non-sticky message is cleared. Attention keeps 
track of one sticky message. 

PostSticky: procedure [s: xstring.Reader, clear: boolean ♦-true, 
beep: boolean ^ false, blink: boolean <~ false]; 

PostSticky appends s to, or replaces, the current sticky message and then displays the new 
message in the window. Its operation is: (1) if the window has a simple message or clear, 
then clear the window; (2) if the window is clear, then clear the current sticky message; (3) 
append s to the current sticky message; and (4) display the new current sticky message. 
Attention makes its own copy of the reader body and bytes of s. beep and blink are the 
same as in Post above. 

ClearSticky: procedure; 

ClearSticky clears any current sticky message. If a sticky message is being displayed, the 
window is cleared. ClearSticky has no effect if there is no sticky message. 



8.2.2 Sticky Messages 



8.2.3 Confirmation Messages 



PostAndConflrm: procedure [ 

s: xstring.Reader, clear: boolean true, confirmChoices: Con-firmChoices <(— (nil, nil], 
timeout: Pro<ess.Ticks <— dontllmeout. 
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beep: boolean <-false, blink: boolean false] 
RETURNS [confirmed, timedOut: boolean]; 

ConfirmChoices: type » record [yes, no: xstring.Reader]; 

dontTimeout: Process.Ticks ■ 0; 

PostAndConfi rm acts like Post in displaying the message $ but waits for confirmation by 
the user. The confirmChoices messages are displayed, and the user should select one of the 
choices with the mouse. If the user selects yes, confirmed is returned true; if no is selected 
or the STOP key is depressed, confirmed is returned false. If confirmChoices. yes # NIL and 
confrmChoices.no = NIL, then only confirmChoices.yes is posted and confirmChoices.no is 
ignored. This is useful for posting a message that the user must see, but for which the user 
gets no choice, such as "Unable to communicate with the printer: CONTINUE". 
PostAndConfi rm absorbs all user input except the stop key and mouse actions over the yes 
and no messages. The client may specify a timeout value, which causes PostAndConf irm to 
return confirmed false and timedOut true if the user does not act within timeout ticks. The 
default value dontTimeout disables this timeout feature. Attention makes its own copy of 
the reader body and bytes of s. 

8.2.4 System Menu 

AddMenultem: procedure [item: MenuOata.ltemHandle]; 

AddMenultem adds item to the global system menu. 

^""^ RemoveMenultem: procedure [item: MenuOata.ltemHandle]; 

RemoveMenultem removes item from the global system menu. There is no effect if item is 
not in the menu. 

SwapMenuJtem: procedure [old, new: MenuData.itemHandle]; 

SwapMenultem swaps new for old in the global system menu. SwapMenultem[old: nil, 
new: item] is equivalent to AddMenultem[item: item] and SwapMenultem(old: item, 
new: nil] is equivalent to RemoveMenultem[item: item]. 

8.3 Usage/Examples 

The following example has a client displaying the name and size of a file. The example uses 
the NSFiie interface to access the file and get the name and size attributes. See the Services 
Programmer's Guide (610E00180): Filing Programmer's Manual for documentation on the 
NSFiie interface. 

PostNameAndSize: procedure [file: NSFiie.Handle ] » { 

nameSelections: NSFti«. Selections ■ [interpreted: [name: true]]; 
attributes: NSFiicAttributes Record; 
rb: xstring.ReaderBody «~ Message[theFile]; 
Attention. Post[s: @rb, dear: true]; - start a new message 
'%«»^ NSFiie. GetAttributes [file, nameSelections, ©attributes]; 

XFormat.NSStringlAttention.formatHandie, attributes.name]; * 
NSFik.ClearAttributes [©attributes]; 
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XFormat.ReaderBody[h: Attention.formatHandle, rb: Message(contains]]; 
XFormat.Decjmal[h: Attention.formatHandle, n: NSFiie.GetSizelnBytes[filel]; 
rb <— Message[bytes]; 

Attention.Post[s: @rb]}; clear defaults to false 

Message: procedure [key: {theFile, contains, bytes}] returns [xstring.ReaderBody] ■ { 
...}; 

An example of the resulting message displayed in the Attention window is 

The file Foo contains 53324 bytes 

The example intermixes use of the format handle and use of the Post procedure. A client 
could clear first, using the Clear procedure, and then display the message by just using the 
format handle. Note: In a multilingual environment constructing a sentence from pieces 
like this is not recommended because the grammar of other languages could cause this 
sentence to be rather confusing. 
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8.4 Index of Interface Items 
Item 

AddMenuitem: procedure 
Clear: procedure 
ClearSticky: procedure 
ConfirmChoices: type 
dontTimeout: Process.Ticks 
formatHandle: xFormat.Handle 
Post: procedure 
PostAndConfirm: procedure 
PostSticky: procedure 
RemoveMenultem: procedure 
SwapMenultem: procedure 
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9.1 Overview 

BackgroundProcess provides basic user feedback and control facilities to clients that want 
to run in a process other than the the Notifier process (see §3.4.1). Once registered with 
BackgroundProcess, the client process can use Attention to post messages, and check to see 
if the process has been aborted by the user. The user can look at the messages posted by the 
process, and abort the process. Fine Point: The implementation of BackgroundProcess is a piugin, so the 
user interface is up to a particular background manager. See Viewpoint friends level documentation for details on 
how to build a background manager. 

9.2 Interface Items 

ManageMe: ManageProc; 

ManageProc: typ€ » procedure ( 
name: xstring.Reader, 
cailBackProc: CailBackProc, 
window: window.Handie 4-niu 
icon: Containe«.OataHandle <-nil« 
context: long pointer^ nil, 
abortabie: boolean false 
1 

returns [finaiStatus: FinaiStatus]; 

CaliBackProc: type a procedure [context: long pointer] 
RETURNS [finaiStatus: FinaiStatus]; 

FinaiStatus: type = machine d£P£noent{ 

importantFaiiure<0), failure, quietSuccess, success, aborted, firstFree, iast(1 5}}; 

quietlfNoUnreadMsg:FinalStatus = firstFree; 
quietlfNoUnreadlmportantMsg: FinaiStatus a succ(firstFree]; 

A client process that wishes to be managed calls IVIanagelVle. The client should already be 
in the process that it wishes to have managed; if the client starts in the Notiiier, tiie client 
should do a fork and call ManageMe from the forked process, name is a string that may be 
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used by the background manager to identify the process to the user; the bytes in name are 
copied by the background manager. After ManageMe is called, the background manager 
will call callBackProc with context to gfive control back to the client process. If the process is 
prepared to catch aborted, then abortable should be true. If the process is not prepared to 
catch ABORTED, then abortable should be false, (see §9.3.2). window and icon may be 
provided for use by the background manager; if the process is tied to a particular window or 
icon, the background manager may use these to allow the user to manipulate the process 
via the window or icon. When the client process is completed or aborted, it should return 
from callBackProc with a finalStatus indicating the outcome of the process. 
ImportantFailure indicates that the user should be warned that the process terminated in a 
way that might need the user's attention, failure indicates that the process failed in some 
way but that we don't need to inform the user in any special way. quietSuccess indicates 
that the process should go away without any final notice to the user, success indicates that 
process succeeded and that a final status message may be posted, aborted indicates that 
the process was aborted by the user. quietlfNoUnreadMsg tells the background manager 
that if there are no unseen messages for this process, terminate as it would with a status of 
quietSuccess. If messages remain to be read, the termination is treated as a status of 
success. quietlfNoUnreadlmportantMsg tells the background manager to terminate as a 
quietSuccess if there are no flagged messages (see FlaglmportantMsg). Fine point: 
quietlfNoUnreadMsg and quietlfNoUnreadlmportantMsg are defined in Bacl<groundPro<e$sExtra. 

UserAbort: procedure [process: process nuilProcess] returns [boolean]; 

ResetUserAbort: procedure [process: process* nullProcess]; 

AbortProc: TYPE » PROCEDURE [context: LONG POINTER]; 
SetAbortProc: procedure [abortProc: AbortProc, process: process*- nil]; 

nullProcess: process * loopholeio); 

Clients of the background manager have a choice about how they are notified when the 
user tries to abort a background task. See §9.3.2 for more details about how these choices 
interact. 

UserAbort returns true if the user has requested that the process be aborted. 
ResetUserAbort clears any pending abort; if the user has requested an abort, UserAbort 
will return true until ResetUserAbort is called or the process terminates.. The client can 
also call SetAbortProc to specify an AbortProc that will be called when the user tries to 
abort a process. The AbortProc will be passed the context pointer that was passed into 
ManageMe; therefore, SetAbortProc can only be called after the client has called 
ManageMe. .Fine point: AbortProc and SetAbortProc are defined in BackgroundProcess Extra. 

For SetAbortProc, UserAbort, and ResetUserAbort, process is defaulted to nullProcess, All 
three procedures assume that the current process is the process that called ManageMe. 
process should only be used if the process calling UserAbort, ResetUserAbort, or 
SetAbortProc is different from the process that called ManageMe. Fine point: nullProcess is 

equivalent to NIL. nullProcess will be removed from future versions of the interface. 

FlaglmportantMsg: procedure [message, comment: xstring. Reader «- nil, process ♦-nil]; 

This procedure lets the background manager know that there is a message that the user 
should see. If the client process terminates with a status of quietlfNoUnreadErrorMsg 
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before the message is read, the background manager will make sure that task is still 
available to allow the user to read the message. The background manager may also use 
this call to may some kind of visual notification to the user that an important message is 
available. The background manager supplied by the Basic Workstation displays a 
property sheet and waits for the user to respond. If message is NIL, the message posted is 
the current message available in the background manager. If message is non-NIL, that 
message will be posted instead. If comment is non-NIL, an extra string will be posted at 
the end of the sheet which may be used to indicate error recovery. If comment is NIL, this 
part of the psheet is not visible. FlaglmportantMsg is synchronous: it will not return until 
the user bugs done on the property sheet. Since the background manager is a plugin, other 
background mangers may behave differently. Fine point: This procedure is currently exported by 
BackgroundPrcxessExtra. 

GetName: procedure [process: process nil] returns [name: xstnng.ReaderBody]; 
SetName: procedure [newName: xstring.Reader, process: process «- nil]; 

These procedures allow the client to manipulate the name of the task. The name is 
originally set by the name parameter to ManageMe; these procedures allow the client to 
change that name. The name is typically used by the background manger to label the task 
for the user. SetName copies the bytes in newName. The bytes from GetName belong to 
the background manager and should be copied if the client wishes to use them. 

Mode: TYPE » {foreground, background}; 
mode: READONLY Mode; 

mode indicates whether applications should FORK background processes or not. Before 
FORKing a background process, applications should check mode and if it is foreground, do 
not do the FORK, but rather do the operation in the foreground process. This is primarily 
used during Cusp programs to synchronize each Cusp statement. 

backgroundCount: READONLY CARDINAL; 

backgroundCount is the current number of background activities registered with the 
background manager. 

cusplsRunning: BOOLEAN; 

Cusp sets this to TRUE during execution of a Cusp program. Applications can interpret 
this in whatever way is appropriate, for example by not posting option sheets. 

9.3 Usage/Examples 

9,3.1 Posting Messages 

Once a client process has called ManageMe, it can freely post messages using Attention. 

Fine point: the exact method the messages will be displayed is up to the background manager. .-Mso, only the 
client process that originally called ManageMe can call Attention directly. If a background process has any 
associated subprocesses that need to use Attention to post messages, it must use a friends level Attention interface 
to associate the subprocess with the client's main background process. 
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9.3.2 Aborting processes 

A client of the background manager can be notified when the user tries to abort a 
background task. There are three ways that the client can be notified. 

If the client calls ManageMe with abortable » true, the background manager will call 
Process.Abort on the process that called ManageMe. That process should be prepared to 

catch ERROR ABORTED. 

The client may also call SetAbortProc with a procedure that will be called if the user tries 
to abort. This procedure will be called only if ManageMe was called with abortable = 
false; if abortable » true, the manager will call Process.Abort instead of calling the 
AbortProc. 

Finally, the client may also call UserAbort at any time. If the client does not enable the 
use of Process.Abort or set an AbortProc, it is the client's responsibility to periodically call 
UserAbort to see if the user has tried to abort the process. If the client does not check 
UserAbort, user attempts at stopping the process will have no effect. The client may call 
UserAbort from inside an AbortProc 

9.3.3 Example 

This example program fragment illustrates the structure of a typical use of 
BackgroundProcess. In this example, a MenuProc is provided that can be called from the 
attention window. The MenuProc immediately forks a process, which reduces its priority 
and then calls BackgroundProcess. The example program posts four messages, pausing 
between each, and checking UserAbort on each pass, 

backgroundName: xstnng.ReaderBody <-xstring,FromSTRING("Background Post"L]; 
abortedString: xstring.ReaderBody <~xstring.FromSTRING["Process canceled ..."]; 

init: procedure » { 

Attention.AddMenultem [ 
MenuOata.Createltem [ 
zone: z, - some private zone 
name: ©backgroundName, 
proc: BackgroundProcessPost] ]; 

BackgroundProcessPost: MenuOata. MenuProc a { 

Process. Detach [fork OoBackgroundProcessPost(s: ©backgroundName]]}; 

DoBackgroundProcessPost: procedure [s: xstring.Reader] a { 
Doit: SackgroundProcess.CallBackPrOC » { 
FOR i : CARDINAL IN [1 ..4] DO 

If BackgfoundProcess.UserAbortQ THEN { 
Attention.Post{@a bortedStri ng] ; 
R£TURN(abortedl}; 
Attention.Post [s: s]; 
Attention.formatHandle.Blanks[2]; 
Attention.formatHandle.Decimal[i]; 
Process.Pause [pro<ess,SecondsToTicks[1 0]]; 
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ENDLOOP; 

RETURN [success]}; 
Process.SetPriority[Pro<ess.priorityBackground]; 

n <-BackgroundPro<ess.ManageMe [name: @backgroundName, callBackProc: Dolt]}; 
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9.4 Index of Interface Items 



Item Page 

AbortProc: type 2 

backgroundCount: readonly cardinal 3 

CallBackProc: type 1 

cuspisRunning: BOOLEAN 3 

FinalStatus: type 1 

FtaglmportantMsg: procedure 2 

GetName: procedure 3 

ManageMe: procedure 1 

ManageProc: type 1 

Mode: type 3 

mode: Mode 3 

nullProcess: process 2 

quiettfNoUnreadMsg: Ftnaistatus 1 

quietlfNoUnreadlmportantMsg: FinalStatus 1 

ResetUserAbort: procedure 2 

SetName: procedure 3 

SetAbortProc: procedure 2 

UserAbort: procedure 2 
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10.1 Overview 



The BlackKeys interface changes the interpretation of the main (central) section of the 
physical keyboard. It includes the data structures that define a keyboard record as well as 
the procedures used to manipulate the keyboard stack. 

The average client uses only the data structures that the BlackKeys interface provides. The 
procedures are reserved for a keyboard manager interested in interfacing between the user 
and the blackkeys stack of keyboards. 



10.2 Interface Items 

10.2.1 Keyboard Data Structures 



The BlackKeys data structures provide the framework for client-defined keys in the main 
(central) section of the physical keyboard. This includes interface to a keyboard picture 
whose keytops may be selected with the mouse to simulate pressing the physical key on the 
keyboard. 

Keyboard: TYPE » long pointer to KeyboardObject <-nil; 

KeyboardObject; type = record { 
table: Tip.Table «-nil, 

charTranslator: Tip.CharTranslator *-(proc; nil. data: nilI. 
pictureProc: Pi ctu reProc <- nil, 
label: xstring.ReaderBody 4-xstring.nullReader8ody, 
clientData: long pointer «-nil]; 

KeyboardObject is the keyboard interpretation data structure. The client may provide its 
own TiP.Table or default it to nil, in which case the NormalKeyboard.TlP table is used. (See 
Appendix A for productions returned by NortnalKeyboard.TlP). A tip. CharTranslator may be 
provided to handle CHAR and bufferedchar productions from a TiP.Table. A PictureProc may 
be provided to be called when installing or removing this keyboard. Absence of such a 
procedure assumes no picture is associated with this keyboard, label is the string that 
appears in the SoftKeys window when the KEYBOARD key is pressed down. Pressing (or 



lO-l 



10 BlackKeys 



selecting) the key marked label invokes this keyboard. clientData is provided to associate 
any other information the client might need to keep with the keyboard. 

PictureProc: type a procedure [ 
keyboard: Keyboard, 
action: PictureActlon] 

RETURNS C 

picture: Picture <-nullPicture, 
geometry: Geometry Table 

PictureProc is a client-provided procedure that is called by a keyboard window application 
when the client's keyboard is being installed (action a acquire) or removed (action = 
release) from the top of the blackkeys stack of active keyboards. The client may use this 
opportunity to map or unmap the picture and geometry table that the keyboard window 
application uses. 

PictureActlon: type a {acquire, release}; 

acquire » client's keyboard is being installed at the top of the keyboard stack (becoming 
the current keyboard). 

release » client's keyboard is being removed from the top of the keyboard stack. 

PictureType: type » {bitmap, text}; 

Picture: type a record ( 
variant: SELEcrtype: PictureType from 
bitmap = > [bitmap: long pointer], 
text 3 > [text: xstring.Reader] 
endcase]; 

The variant of the record, Picture, allows the client to present its keyboard window in either 
bitmap or textual form. (See the Key board Window interface for a discussion of the 
structure behind a keyboard bitmap.) text is pointed to by an xstring.Reader. The text is not 
copied. 

nuliPicture: bitmap BiackKeys.Picture » [bitmap[NiL]]; 

The variable nuliPicture represents a null entry to the keyboard window. 

Geometry Table: type - long pointer; 

A geometry table allows access to the data structure. (See the KeyboardWindow interface 
chapter for discussion of the structure of a geometry table.) 

10.2.2 Getting a Handle to the Current Keyboard 

BiackKeysChange: Event. EventType; -- ATOM defined as "BlackKeysChange" 
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Changing the keyboard at the top of the blackkeys stack of keyboards results in the 
notification BlackKeysChange through the Event mechanism. The eventData supplied by 
the Event.Notify is the current keyboard handle. 

GetCurrentKey board: procedure returns [current: Keyboard]; 

GetCurrentKeyboard returns the current keyboard from the top of the blackkeys stack. 



10.2.3 Procedures 

The following procedures are NOT expected to be used by Applications programmers. 
Instead see KeyboardKey .SetKeyboard. 

Push: PROCEDURE (keyboard: Keyboard!; 

The Push procedure installs a black key interpretation at the top of the blackkeys stack of 
keyboards. The TiP.Table and/or TiP.CharTransIator are registered with tip and the event 
BlackKeysChange is broadcast. 

Remove: procedure [keyboard: Keyboard]; 

The Remove procedure removes the keyboard from the stack of active keyboards and resets 
the TiP.Table and TiP.CharTransIator as applicable. The event BlackKeysChange is broadcast 
if keyboard is on the top of the blackkeys stack. 

May raise the ERROR Bia^kKeys.lnvalidHandle. 

Swap: procedure [old: Keyboard, new:Keyboard]; 

The Swap procedure is designed to change black keys' interpretations without returning to 
some previous or other default value in between. It is essentially the equivalent of a 
Remove followed by a Push. The event BlackKeysChange is broadcast if the keyboard being 
removed was on top of the stack. 

May raise the error BlackKeysJnvaiidHandle. 

10.2.4 Errors 

InvaiidHandte: error; 

This error is raised if the keyboard passed to Remove or Swap (old) is not in the set of 
active BlackKeys keyboards. 

10.3 Usage/Examples 

10,3,1 Defining a Keyboard Record 
DefineKayboard: procedure = 

BEGIN 

nameString: xstring.ReaderBody ♦-xstring.FromSTRlNG("SwahirrL] 



10-3 



10 BlackKeys 



swahiliKeyboardRecord: siackKeys.KeyboardObject *-[ 
table: NIL, 

charTranslator: [MakeChar, nil], 
pictureProc: MapBitmapFile. 

label: xstring.CopyToNewReaderBodyt@nameString, Heap.systemZonell; 
"Save the pointer to the record somewhere for future use — 
END; -Def/neKeyboard - 

MapBitmapFile: BJackKeys,PictureProc » 

BEGIN 

pixPtr: BiackKeys.Picture.bitmap 4-BtackKeys.nullPicture; 
SELECT action from 
acquire » > 

{"Do the right thing to map the bitmap. Uses the default geometry table. — 
RETURNlpixPtr, Keyboardwindow.def aultGeometry] }; 
release « > {--Do the right thing to unmap the bitmap — 

RETURN[BlackKeys.nullPicture.NIL] } 

END; — MapBitmapFile 
MakeChar: Tip.KeyToCharProc ■ 

BEGIN 

-Map bufferedChar to desired xstnng. Character 
END; - MaAreChar 
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10.4 Index of Interface Items 



Item Page 

BlackKeysChange: Event.EventType 2 

Geometry Table: type 2 

GetCurrentKeyboard: procedure 3 

invalidHandle: error 3 

Keyboard: TYPE 1 

KeyboardObject; type 1 

nuilPicturerbitmap Picture 2 

Picture: type 2 

PictureAction: type 2 

PictureProc: type 2 

PictureType: type 2 

Push: procedure 3 

Remove: procedure 3 

Swap: procedure 3 
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11.1 Overview 

BodyWindowParent provides a facility for creating body windows in a subwindow. The 
client may provide several procs for dealing with scrolling multiple body windows within 
the parent viewing region. For a comprehensive view of all the subwindow interfaces and 
their intended use, see the Subwindow Overview chapter. 

11.1.1 Body windows Discussion 

''-^^^ A bodyParent window has an interior window that is a child of the bodyParent and is 

exactly the size of the available window space in the bodyParent (that is, the bodyParent 
minus its scrollbars). The interior window may have child windows created by the client. 
These children of the interior window are called body windows. The client may create an 
arbitrary number of body windows and arrange them in an arbitrary fashion. Note: Since 
the body windows are children of the interior window, they are clipped by the interior 
window. A client could, for example, create a body window that is very much taller than 
the interior window and accomplish scrolling by simply sliding the body window around 
inside the interior window. (This is actually what the default scrolling does; for more 
detail, see this Chapters section on scrolling). 

Body windows are created by calling BodyWindowParent.CrsateBody. This returns a 
Window.Handle. The client can create an arbitrary number of body windows. Each body 
window is a child of the bodyParent's interior window. The body windows may overlap or 
not. They can be in any arrangement the client finds useful. Some common arrangements 
of body windows are as follows: 

• One very long body window. 

This is easy to scroll by simply sliding the body window, which is what the default 
scrolling does. 

• One body window with BodyWindowJustFits a true. 

This is one way to display an infinite amount of data, such as a Tajo-like editor. The 
client must keep track of what is currently in the window, use adjust procs, do 
scrolling, and so forth. This is dilTicult to implement. 
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• Several body windows about the size of the interior, adjacent, non-overlapping. 

This is another way to display an infinite amount of data. The client lets 
BodyWindowParent do default scrolling, which slides the body windows up or down 
and then calls the client to supply more body windows when it runs out. The client 
might put one page of text into each body window, supplying pages to 
BodyWindowParent scrolling as needed. 

• Several body windows smaller than the interior, adjacent, non-overlapping. 

Note: Body windows can themselves have child windows, and so on, A client might 
implement frames in a document editor by making each frame a child of a body window. 

11.2 Interface Items 



11.2.1 BodyParent window 

Create: procedure [ 

parent: wtndow.Handle. 

vertical Scroll bar: boolean +-true, 

horizontalScrolibar: boolean true. 

adjuStPrOC: Adjustable window .A djuStProc «-NIL. 

garbageCollectBodiesProc: GarbageCollectBodiesProc 4~nil, 

moreScrollProc: MoreScrollProc <- nil, 

scroll barlnfoProc: s<roiibar,ScroiibaHnfoProc <-nil. 

thumbFeedbackProc: Scroiibar.ThumbFeedbackProc ♦-nil, 

thumbScrolIProc: s<ronbar.Thunr>bScrollProc «- DefaultThumbScroll, 

zone: uncounted zone]; 

Takes a window and makes it a body parent window. An interior window is created (child 
of the body parent) that becomes the viewing region for future body windows. 
verticalScrollbar and horizontalScrolibar are attached as instructed by the client provided 
BOOLEANS. The scroHbarlnfoProc will be called when the user thumb scrolls and then the 
appropriate feedback (like the ViewPoint diamond or the tajo bar) will be painted in the 
thumbing region of the scrollbar. Fine Point: The client shouJd call GetlnteriorDima when deterimining 

the offset and portion. moreScrollPfOc and garbageCollectBodiesProc are described in §2.3. 

ISlt: PROCEDURE] 

parent: window.Handle 

RETURNS [BOOLEAN]; 

Determines if parent is indeed a bodyParent created by calling BodyWindowParent.Create. 
Returns TRUE if it is, false if not. 

Destroy: procedure (parent: window.Handle]; 

Destroy destroys the parent window, its descendents and any associated data. 
Adjust: AdjustableWindow.AdjustProc; 

Adjust should be called when the body parent is being resized (before and after the 
SlideAndSize). 
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SetAdjustProc; procedure [ 
parent: window.Handle, 
new: AcijustabieWinclow.AdjustProc] 
RETURNS [old: AdjustableWlndow.AdjuStProcJ; 

new will be called whenever parent is changing size. 

11.2.2 Body windows 

CreateBody: procedure ( 

parent; window.Handle <-nil, 

box: Window. Box <- 110,01. [0,1NTEGER.LASTI1, 

displayProc; window.DisplayProc. 
notifyProc: Tip.NotifyProc, 
c]earingRequired:S00LEAN ^TRUE, 
wIndowPane: boolean <- false, 
under, cookie, color: boolean <- false ] 
returns [body: window.Handle]; 

Creates a body window that is a descendent of parent. If parent is nil, body will be an 
orphaned window that can be installed at a later date. (See InstallBody below.) If 
box.dims.w = 0 THEN box.dims.w ^ size of parent's interior. If box.dims.h = 0 THEN 
box. dims. h t- size of parent's interior. notifyProc will be attached to body and 
TiPStar.NormalTableO. ciearingRequired, windowPane, under, cookie, and color are 
described in the Window chapter. If a body is created within a visible parent, the client 
must call window, ValidateTree[body] to effect the change on the screen. 

InstallBody: PROCEDURE(body: window.Handle, parent: window.Handle]; 

Installs the body window in the tree of parent as the eldest sibling. 

OestallBody: pROCEDURE[body: window.Handle]; 

Removes the body from its parent's window tree. 

DestroyBody: procedure [body: window.Handle]; 

Destroys the body window and associated data. 

11.2.3 Scrolling 

Only part of an object is usually visible to the user at any one moment in the interior of a 
bodyParent. The user can request to see more of the object by scrolling the contents up or 
down inside the bodyParent. The user can perform three kinds of scrolling by using the 
scrollbars. (1) He can move the contents a little at a time by pointing at the arrows (up, 
down, left, right) in the scrollbars. (2) He can move the contents a page or screenful at a 
time by pointing at the plus ( +- ) and minus (-) signs. (3)He can jump to any arbitrary place 
within the entire extent of the object being viewed by pointing in the blank part of the 
vertical scrollbar (this latter operation is called thumbing). 

BodyWindowParent provides various levels of support to a client for performing these 
scrolling operations. The client can allow BodyWindowParent to do all the scrolling 
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functions, the client can do some of them and leave the rest to BodyWindowParent, or the 
client can do all scrolling operations. Much of this decision will be based on how the client 
chooses to arrange body windows within the bodyWindowParent (see the section on body 
windows above and more discussion below). First, we will describe the various types of 
scrolling and scrolling procedures that a client can supply; then we will describe the 
default scrolling procedures provided by BodyWindowParent. 

In the simplest (for the client) case, one body window contains the entire extent of the 
object being viewed. BodyWindowParent can handle all scrolling in this case. The client 
simply does nothing. When the user points at an arrow, BodyWindowParent moves the 
body window a small amount. When the user point at plus or minus, BodyWindowParent 
moves the body window by one interior window's height. When the user thumbs, 
BodyWindowParent will move the body window to an appropriate place based on its 
overall height. 

In a slightly more complex case, body windows are butted up against one another. When 
the user points at an arrow, BodyWindowParent moves all the body windows a small 
amount. When the user point at plus or minus, BodyWindowParent moves all the body 
windows by one interior window's height. When the user thumbs, BodyWindowParent 
moves all the body windows to an appropriate place based on the combined overall height 
of the body windows. However, in this case the client often does not have the entire extent 
of the object displayed in these body windows but rather wants to tack new body windows 
on each end as these body windows are scrolled off. The client can do this by providing a 
MoreScroilProc for the shell. BodyWindowParent calls the client's MoreScrollProc 
whenever it runs out of body windows. ,^11^ 

In the most complex case, the client has a single body window that "just fits" (see 
SetBodyWindowJustFits in the section on body windows), and only part of the entire object 
is displayed at any one time. The client must provide all the scrolling functions for this 
case. This means providing a Scrollbar.SingleScrollProc (to handle the user's pointing at 
the arrows, plus, and minus) and a Scrollbar.ThumbScrollProc (to handle the user's 
thumbing). See the Chapter on Scrollbar for further information on setting the 
SingleScrollProc. 

Of course, the client may provide its own scrolling procedures for any of the above cases, 
even the simple one, to override the type of scrolling that BodyWindowParent provides. 
But at some point it would be wiser to register a new subwindow type instead. If 
BodyWindowParent type AttachScrollbars and Adjustment are desireable then the client 
should use the Standard subwindow procs exported by SubwindowFriends when creating 
their own unique type. 

11.2.3.1 ScroUProcs 

The following ScrollProc types are passed in by the client when creating a bodyParent 
window. Any or all of them may be defaulted to NIL. 

MoreScroliProc: TYPE = procedure [ 
parent: window.Handle, 

type: ScroJIbar.Ty pe, ^iBl 
flavor: MoreFIavor, 
amount: cardinalI; 
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MoreFlavor: type = {before, after}; 

The MoreScroliProc is called when we run out of body windows during scrolling. (See 
discussion above) .amount is pixels. 

The client's moreScroll procedure is responsible for adding and deleting body windows from 
the bodyParent. The case being handled is that in which the client has a large number of 
pages to display to the user and wishes to manifest only a few. Then we need to handle the 
case in which system scrolling would make a non-manifest page visible, and there is no 
body window for it. Whenever the system is about to perform a scroll function, it checks to 
see if the scroll action would move the visible portion of the bodies off the end of the 
existent body windows. If so, it calls a non-nil client MoreScroliProc, indicating how much 
more body window may be displayed. The client may augment the collection of body 
windows or not. The system routines will not scroll past the end of the body windows. 

GarbageCollectBodiesProc; type a procedure [ 
parent: window. Handle, 
body: Window. Handle, 
type: Saollbar.Typej: 

Called when body is no longer visible. Allows client a chance to destroy or reuse the body. 



1 1.2.3.2 Getting and Setting ScrollProcs 



The following procedures Get and Set the ScoUProcs associated with parent. 
GetScrollProcs: procedure (parent: window.Handle] 

RETURNS [ 

garbageCollectSodiesProc; GarbageCollectBodiesProc. 
moreScrollProc: MoreScroliProc, 
scrollbarlnfoProc: Scroiibar.ScrollbarinfoProc 
thumbFeedbackProc: Scroiibar.ThumbFeedbackProc, 
thumbScrollProc: ScroJibar.ThumbScrollProc]; 



SetMoreScrollProc: procedure [ 
parent: window.Handle. 
new: MoreScroliProc] 
RETURNS (old: MoreScrollProcj: 

SetScrollbarlnfoProc: procedure { 
parent: window.Handle. 
new: Scrolibar.Scrol I ba rl nf oProc] 
returns (old: Saoiibar. Scroll bar! nfoProcJ; 

SetGarbageCollectBodiesProc: procedure ( 

parent: window.Handle, 

new: GarbageColiectBodiesProcl 

returns (old: GarbageCollectBodiesProc]; 
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SetThumbFeedbackProc: procedure ( 
parent: window.Handle, 
new: scroiibar.ThumbFeedbackProc] 
RETURNS (old: Scroiibar.ThumbFeedbackProc]; 

SetThumbScroHProc: procedure ( 
parent: window.Handle, 
new: Scroiibar.ThumbScroilProcl 
RETURNS [old: ScroUbar.ThumbScroliPfOC]; 

11.2.3.3 Default ScroUProcs 

DefauitSingieScroll: Scroilbar.SingieScrollProc; 
DefaultScrollbarlnfo: Scroiibar.ScrollbarlnfoProc; 
DefaultThumbScroll: Scroiibar.ThumbScrollProc; 

Calling DefauitSingieScroll, DefaultScrollbarlnfo or DefaultTh umbScroll will invoke 
standard scrolling of window in specified flavor and amount. Can be used to set the 
desired Procs or called independently. The type of scrolling provided is as described in the 
General Discussion Simple Case in Sections 1.1 and 2.3 

11.2.4 Utilities 

GetZone: procedure [parent: window.Handle] RETURNS[zone: uncounted zone]; 

Returns the zone associated with the bodyParent window. 

ParentFromBody: procedure [body: window.Handle] 
RETURNS [parent: window.Handle]; 

Given a body window returns its body parent subwindow. 

GetBody: procedure [parent- window.Handle] 
RETURNS [body: Window.Handle]; 

Returns the first body window in parent. 

GetScrollbar: rocedure (window: window.Handle, type; Scroiibar.Typej 
RETURNS [scrollbar: window.Handle]; 

Given a body window or bodyParent window, returns the associated scrollbar of type. 

GetlnteriorOims: procedure [parent: window.Handle] 

RETURNS (dims: Window.Dims]; 

Returns the dimensions of the viewing region of the body parent subwindow. 
IsBodyWindowOutOfinterior: procedure (body: window.Handle] 

RETURNS [BOOLEAN]; 
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Returns true If all of body is sticking out of the viewing region, FALSE if any part of body is 
within the viewing region. 

EnumerateBodies: procedure ( 
parent: window.Handle, 
proc: BodyEnumProcI 
RETURNS [Window.Handle]; 

EnurrierateBodieslnOecreasingY:PROCEDUR£( 

parent: window.Handle. 

proc: BodyEnumProcI 
RETURNS [Window.Handle]; 

EnumerateBodieslnlncreasingY:PROCEDURE[ 

parent: window.Handle, 

proc; BodyEnumProcI 
RETURNS [Window.Handle]; 

The EnumerateBodiesxxx procedures enumerate all the body windows in parent, calling 
proc for each body window until proc returns stop = true. EnumerateBodies enumerates 
the bodies in the order in which they appear in the parent tree. 
EnumerateBodieslnlncraasingY enumerates the body windows in increasing order of 
bodyBox.place.y, and EnumerateBodieslnOecreasingY enumerates the body windows in 
decreasing order of place. y. Each procedure returns the last body window enumerated or 
NIL if all body windows were enumerated. These procedures are especially handy for clients 
that do their own scrolling. To minimize repainting when scrolling a set of body windows 
upward, it is important to move the upper ones first, and vice versa. 

BodyEnumProc:TYPE = proc (body: Window.Handle] 

RETURNS [Stop: 800LEAN ♦-FALSE); 

Stop a true will terminate the enumeration. Fine Point: deatalling or destroying body within the 
Bo<iy£nuinProc is allowed. 

11.2.5 Errors 

Error: error (code: ErrorCodej; 

ErrorCode: TYPE = {noBodieslnParent. notABodyWindowParent}; 

11.3 Usage/Examples 

—In impl for Body sub windows: 

AttachScrollbarsToBodySWiSubwindowFriends.AttachScrollbarsProc = { 
BodyWindowPafent.Create{...]. } 
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11.4 Index of Interface Items 



Item Page 

Adjust: PROCEDURE 2 

BodySnumProc: type 5 

Create: procedure 1 

CreateBody: procedure 2 

DefaultScrollbarlnfo: Scrollbar. ScrollbarlnfoProc 4 

DefaultSingleScroli: Scrollbar.SingleScrollProc 4 

DefaultThumbScroll: Scrollbar.ThumbScrollProc 4 

DestaiiBody: procedure 2 

Destroy: procedure 2 

DestroyBody: procedure 3 

EnumerateBodies: procedure 5 

EnumerateBodies InDecreasingY: procedure 5 

EnumerateBodies InlncreasingY: procedure 5 

Error: error 5 

ErrorCode: TYPE 5 

GarbageCollectBodiesProc: TYPE 3 

GetBody: procedure 4 

GetlnteriorOimsiPROCEDURE 4 

GetScrollbar: procedure 4 

GetScrollProcs: procedure 3 " 

GetZone: procedure 4 

Install Body: procedure 2 

IsBodyWindowOutOflnterior: procedure 4 

Isit: procedure 2 

MoreFlavor: type 3 

MoreScrollProc: type 3 

ParentFromBody: procedure 4 

SetAdjustProc: procedure 2 

SetGarbageCollectBodiesProc: procedure 3 

SetMoreScrollProc: procedure 3 

SetScroilbarlnfoProc: procedure 3 

SetThumbFeedbackProc: procedure 4 

SetThumbScroilProc: procedure 4 




Busylccn 



12.1 Overview 



Busy! con provides the client with a way to make file-backed icon object "busy." An object 
that is busy cannot be operated on by the user. The notion of an object being busy is a user- 
interface level notion; clients are still responsible for obtaining any necessary locks on an 
object. Making an object busy insures that normal user operations (open, drop-on, props, 
and so forth) cannot be invoked. If an object to be made busy is visible on the desktop or in 
a container, the appearance of that object will change to make the object appear busy to the 
-user. Whether or not the object is visible, the object is still marked as busy in the 
Containee cache so that the next time the object is visible, it will appear busy. See the 
Containee chapter for documentation on the Get/SetCachedBusy operations. 



12.2 Interface Items 



IsBusy: procedure [ref: NSFiie. Reference, w: window. Handle ♦-nil] 
RETURNS [yes: boolean]; 

Returns true If ref is busy. If non-nil, w is used as a hint for where to look: either the 
desktop window or a FileContainerSource-backed container window that ref might be 
found in. If ref is not found in w, IsBusy will search the desktop and all open 
FileContainerSources for ref. If ref is still not found, IsSusy will check the Containee cache 
to see if the object is busy (see the Containee chapter for more information.) 

IsBusy will only fmd files in container windows backed by a FiieContainerSource or a 
source built on FiieContainerSource. 

BusyStatus: type a {succeeded, notFound, stateNotChanged, notAJlowed}; 

MakeBusy: procedure [ref: NSFile.Reference, w: window. Handle ♦-nil] 
RETURNS [result: BusyStatus]; 

MakeUnbusy: procedure [ref: NSFile.Reference, w: window. Handle ♦-nil] 
RETURNS [result: BusyStatus]; 

MakeBusy looks for ref on the desktop or in an open container window backed by a 
FiieContainerSource. w is a hint that ref is in that window; w may be the desktop window 
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or a container window. If w is NIL, MakeBusy and MakeUnbusy look in all open 
FileContainerSource-backed container windows and on the desktop. Both operations 1^%, 
return result to indicate the outcome of the operation. If ref is part of the selection, the 
selection is cleared (but see notAllowed status below.) 

succeeded indicates that the icon for ref was found and the icon picture was changed. 
notFound means that an object for ref was not found. The icon picture was not changed, but 

the Containee cache was updated. 

stateNotChanged means that ref was found but was already in the desired state. 
notAllowed is returned if the operation is not allowed at the moment. This can occur if the 
user calls MakeBusy from the background but the object is part of the user's selection. 
MakeBusy will not make the object busy, but instead will return a status of notAllowed. 

IsBusy will only find files in container windows backed by a FileContainerSource or a 

source built on FileContainerSource. Files in other types of container sources will not have 
their picture changed by these procedures, 

12.2 Usage 

Clients are responsible for making sure an object is properly locked before making the 
object busy. If an object is just made busy without acquiring any other locks, there is 
nothing to stop some other program that has a reference to a file from operating on that 
file. 

A typical way to use this interface may to do some background operation on an icon. The 
flow would look something like this. 

• The user selects an icon and invokes a menu command. 

• In the menu command (and thus in the foreground) the command does a Selection.Convert 
to get a reference to the file. 

• The menu command opens the file and get an NSFile lock on 

• The command calls MakeBusy to make sure the user cannot operate on the file. 

• The command forks some operation. 

• When the operation is done, the client would unlock the file and closes the file handle 

• To finish up, the client calls MakeUnbusy to return the icon the the user's control. 

In this example, the client does not need to worry about whether the icon was on the 
desktop or inside a folder. Busylcon took care of making the icon busy. 
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12.3 Index of Interface Items 

Item Page 

Busy Status: type 1 

IsSusy: procedure 1 

MakeBusy: procedure 1 

MakeUnbusy: procedure 1 
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13.1 Overview 

BWSAttributeTypes defines the NSFito.ExtendedAttributeTypes that are used by ViewPoint 
as well as the first NSFii«.ExtendeclAttributeType available for client use. 

The only extended attributes defined here are the ones that can be attached to any file, 
such as mailing and filing application attributes. Attributes that are unique to a particular 
application's files should be defined privately within that application. Several applications 
can use the same extended attributes because application A should never be reading the 
attributes from application B's files and vice versa. Fine point: Several application-specific attribute 
types are included in this interface for compatibility. 

The extended attributes that can be attached to any file, leaving a few spare ones for future 
use. are defined here. Also defined are the first available "application attribute" 
(firstAvaiiabieAppiicationType). Caution: An application should not use an extended 
attribute smaller than this one, nor should an application use an extended attribute larger 
than lastBWSType. 

13.2 Interface Items 



13.2.1 Available Application Types 

firstAvaiiabieAppiicationType: NSFite.ExtendedAttributeType ■ . . . ; 
lastBWSType: NSFito.ExtendedAttributeType ■ . . . ; 

Applications should only use the types in the range [firstAvaiiabieAppiicationType . . 
lastBWSType]. firstAvaiiabieAppiicationType is the first extended attribute type that 
applications can use to store application-specific attributes. Caution: An application 
should not use an extended attribute smaller than firstAvaiiabieAppiicationType. 
lastBWSType is the last extended attribute type that applications can use to store 
application-specific attributes. Caution: An application should not use an extended 
attribute larger than lastBWSType. 
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If a Viewpoint client needs more attributes than the number in this range, see the 
NSFiling group to obtain a range specific to that client. 

13.2^ Viewpoint Types 

Consult the Mesa interface for the exact assignment of ViewPoint-specific types. 
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13.3 Index of Interface Items 

Item Page 

firstAvailableApplicationType: NSFii«.ExtendedAttributeType 1 

lastBWSType: NSFite.ExtendedAttributeType 1 
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14.1 Overview 

BWSFileTypes defines several NSFite.Types used by ViewPoint. Applications should not use 
these types. (Also see the Catalog and Prototype interfaces.) 

ViewPoint clients must manage all file types that they use. Ranges of file ty^es may be 
obtained from the Filing group. 

14.2 Interface Items 

root: NSFiie.Type - . . . ; 

The root file of the volume has this type. The root has children that are called (by 
convention) catalogs. 

desktop, desktopCatalog: NSFii«.Type ■ . . . ; 

The desktop catalog contains all the desktops on a workstation. An individual desktop has 
the same type as the desktop catalog. 

prototypeCataiog: NSFito.Type ■ 

The prototype catalog contains prototype files for each application. A prototype file is a 
blank application file that the user can make copies of, such as Blank Folder, or Blank 
Document. (See the Prototype interface.) 

systemFiieCataiog: NSFiie.Type ■ . . . ; 

The system file catalog contains system files, such as the beds for an application, message 
files, font files, TIP flles,and so forth. (See the Catalog interface.) 
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14.3 Index of Interface Items 

Item Page 

desktop: NSFii«.Type 1 

desktopCatalog: NSFiic.Type 1 

prototypeCatalog: Nsnto.Type 1 

root: NSFik.Type 1 

systemFileCatalog: NSFii«.Type 1 
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15.1 Overview 

BWSZone defines several zones, each with different characteristics, that ViewPoint clients 
may use, as appropriate. 

15.2 Interface Items 

All zones are created at boot time and exist for the duration of tiie boot session. 

permanent: UNCOUNTED zone; 

Permanent: procedure returns [uncounted zone]; 

permanent is intended for nodes that are never deallocated. It has infinite threshold. 
Permanent returns permanent. 

logonSession: uncounted zone; 

LogonSession : procedure returns [uncounted zone]; 

logonSession is intended for nodes that last for a logon/logoff session. logonSession is 
emptied of all nodes at each logoff (that is, H«ap. Flush). LogonSession returns 
logonSession. logonSession is created at boot time and is flushed at logoff. 

shortLifetime: uncounted zone; 

ShortLifetime: procedure returns [uncounted zone]; 

shortLifetime is intended for nodes that are allocated for a very short time, such as during 
a notification. ShortLifetime returns shortLifetime. 

semipermanent: uncounted zone; 

Semipermanent: procedure returns [uncounted zone]; 

semipermanent is intended for nodes that are allocated for a very long time but that might 
occasionally have to be expanded. Semipermanent returns semipermanent. 
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15.3 Index of Interface Items 
Item 

LogonSession: procedure 
logonSession: uncounted zone 
Permanent: procedure 
permanent: uncounted zone 
Semipermanent: procedure 
semipermanent: uncounted zone 
ShortUfetime: procedure 
shortLifetime: uncounted zone 
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16.1 Overview 

Catalog manipulates files called caUUogs that are direct descendants of the root file on a 
NSFlling volume. Each catalog is uniquely identified by its file type. Files can be opened 
and created within a catalog. Catalogs can be opened, created, and enumerated. 

Vie^vpoint creates a system file catalog and a prototype catalog (see the Prototype 
interface) at boot time. The sjrstem file catalog typically holds font files, TIP files, icon 
pictxire files, message files,and so forth. 

16.2 Interface Items 

16.2.1 Finding and Creating Files in a Catalog 

GetFile: procedurc [ 

catalogType: NSFii«.Type 4-BWSFii«Typ«s.systemFiieCatalog, 

name: xstring.Reader, 

readonly: boolean 4- false, 

session: NSFii«.Session 4-NSFii«.nullSession] 

RETURNS [file: NSFii«.Handle]; 

GetFile finds a file with name name in the catalog with type catalogType. If the file cannot 
be found, NSFii«.nuilHandle is returned. 

CreateFile: procedure [ 

catalogType: NSFit«.Type 4-BWSFii«TypM.systemFlleCatalog, 

name: xstring.Reader, 

type: NSFiic.Type, 

IsDirectory: boolean 4- false, 

size: long cardinal ^ 0, 

session: NSFUe.Session «-NSFii«.nullSession] 

RETURNS [file: NSFUe.Handle]; 

CreateFile creates a file with the specified attributes (name, type, isOirectory, size in bytes) 
in the catalog with type catalogType. 
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16.2.2 Operating on Catalogs 

Open: procedure [ 

cataiogType: NSFfi«.Type, 

session: NSFii«.Session 4-NSFii«.nuilSession] 

RETURNS [catalog: NSFii«.Handle]; 

Opens the catalog with type cataiogTypa. If the catalog cannot be opened, it returns 
NSFil«.nullHandl6. 

Oeata: procedure [ 

name: xstring.Reacier, 

cataiogType: NSFite.Type, 

session: NSPii«.Session 4-NSFii«.nuliSession] 

RETURNS [catalog: NSF{i«.Reference]; 

Creates a catalog with the specified name and type. If the catalog already exists or cannot 
be created, it returns NSFii«.nuilReference. Note: Even though the file can be identified by 
type only, the name should be logical (such as '*System Files'*) so that any tools written to 
manipulate catalogs can display these names. 

Enumerate: procedure [proc: CatalogProc]; 

CatalogProc: type > procedure [cataiogType: NSFii«.Type] 
RETURNS [continue: boolean 4- true]; 

Enumerate calls the client-supplied proc for each existing catalog or until proc returns 

FALSE. 

beforeLogonSession:NSFii«.Session; 

beforeLogonSession is a session that can be used when calling a Catalog procedure before 
any user has logged on, such as at boot time. It is set to be the default session until a user 
logs on. 
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16.3 Index of Interface Items 

Item Page 

beforeLogonSession: NSFii«.Session 2 

CataiogProc: type 2 

Create: procedure 2 

CreateFile: procedure 1 

Enumerate: procedure 2 

GetFile: procedure 1 

Open: procedure 2 
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Containee 



17.1 Overview 



Containee is an application registration facility. An application is a software package that 
implements the manipulation of one type of file. Containee is a facility for associating an 
application with a file type. 

17.1.1 Background 

All NSFiies have: 

• a name 

• a file tjrpe (long CARDINAL) 

• a set ofattributes, such as create date 

• either: 

- content, such as a document 

- children that are also NSFiies, such as a folder 

An NSFiie that has children is often called a directory. Fine Point: An NSFUe can actually have both 
content and children, that is ignored for now to simplify this discussion. Since the children of an NSFiie 
can themselves have children, NSFiie supports a hierarchical file system. 

A Viewpoint desktop is backed by an NSFiie that has children. Each child file of the 
desktop's NSFiie is represented on the screen by an iconic picture. 

Each application operates on NSFiies of a particular file type. For example, ViewPoint 
documents operate on NSFiies with file type of 4353. Each document icon is actually an 
NSFiie of type 4353. Each application needs a way to register its ability to operate on files of 
a particular type. Containee is such a facility. 

17.1.2 Containee.Implementation 

An application's ability to operate on Hies of a particular type includes such operations as: 

• Display of the iconic picture (full size and tiny). 

• Open, performed when the user selects an icon and presses OPEN. 

• Properties, performed when the user selects an icon and presses PROPS. 
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• Take the current selection, performed when the user drops an object onto an icon by jiili, 
COPYing or MOVEing a selected object to an icon. 

An application registers itself by calling ContainM.Setlmplementation, supplying a file type 
and a Contain««.lmplementation. A ContainM.lmpienientation is a record that contains two 
important procedures: 

• A procedure for displaying an icon picture (ContainM.PictureProc) . 

• A procedure for performing various operations on an icon, such as open, create a 
property sheet, and take the current selection (ContainM.GenericProc). 

This application registration allows the ViewPoint desktop implementation to be open- 
ended. The desktop implementation itself does not know how any file behaves. Rather it 
depends on applications registering their ability to operate on particular file types. The 
desktop implementation, at logon, simply enumerates the child files of the desktop's NSFiie 
(using NSFil«.List), obtaining the file type for each child. For each child file, the desktop 
implementation gets an application's Contaiiraclnipiementation by using the child file's file 
type (and Contain««.Getlmplementation) and then calls that application's 
ContainM.PictureProc to actually display an icon picture. Similarly, when the user selects an 
icon on the desktop and presses OPEN, the desktop implementation uses the file type of the 
file at that place on the desktop to get the application's Contain««.impiementation and then 
calls the application's Contain««.GenericProc to get a StarWindowSheil created. The 
implementations of Folders and File Drawers are similar to the desktop implementation in 
this respect. 

17.1.3 Containee.Data 

An application needs to distinguish one file from another. Two different documents may be 
the same file type, but probably have different names and different contents. Whenever an 
application's Contains. DispiayProc or Containee.GenericProc is called, the particular file 
being operated on by the user is passed to the procedure through the Containee.OataHandle 
parameter. A ContainM.OataHandle is a pointer to a Containee.Data that is simply a record 
with an NSFile.Ref erence in it. An NSFile.Ref erence uniquely identifies a particular file and 
allows the application to utilize various NSFiie file-accessing procedures for manipulating 
the file. 

17.2 Interface Items 

17.2.1 Items for Application Implemen tors 

Setlmpiementation: procedure [NSFiie.TypeJmpiementation] 
RETURNS [ Impiementation]; 

Setlmpiementation associates an Implementation record with a particular file type and 
returns the previous Impiementation that was associated with that file type. An 
application calls Setlmpiementation to register its ability to operate on files of a particular 
type. 

When an application calls Setlmpiementation, it is convention to save the old 
implementation to backstop operations that the new implementation does not support. For 
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example, most GenericProcs have an endcase that calls the old application's GenericProc 
for atoms it does not understand. 

Implementation: type ■ record [ 
impiementors: long pointer ^ nil, 
name: xstring.ReaderBody 4-xstring.nullReaderBody, 
smaliPictureProc: SmaliPictureProc «-nil, 
pictureProc:PictureProc 4- nil, 
convertProc: Seiection.ConvertProc nil. 
genericProc:GenericProc4-NiL ]; 

When an application registers its ability to operate on files of a particular type (i.e, calls 
Setlmplementation), it supplies an Implementation record. The Implementation record 
defines the behavior of all files of that type. 

Impiementors is provided for the convenience of clients that may want to associate some 
application-specific data with the Implementation record. Note: This data is one per 
application, not one per file. 

name is a user-sensible name for the objects that the Implementation manipulates, such as 
"Docimient'* or "Spreadsheet." This string typically comes from XMessage. The bytes of 
name are not copied— the storage for name must be allocated forever (which is easy to do 
using XMessage). 

smaliPictureProc is a procedure of t3rpe SmaliPictureProc that returns a character. This 
procedure is describe below. 

pictureProc is called whenever the file's full-sized icon picture needs to be painted. (See 
PictureProc.) 

convertProc is called to convert the file into another form, such as an Interpress master. 
This procedure is used when the owner of the current selection is a container, such as a 
folder, and the selection is actually a file (row) in the container. The owner of the selection 
(i.e., the container implementation) may be called to convert the selected file (row), but 
only the application that implements that file's type can do the conversion. The 
convertProc allows the owner of the selection to pass the conversion request along to the 
application. The data parameter to the convertProc is a Contain««.OataHandle. This 
convertProc does not need to be able to convert to a target type of file or fileType, but rather 
should call Containe«.OefaultFileConvertProc for these target types. If the application does 
not perform conversion to any target types, ContainM.OefaultFileConvertProc should be 
provided as the convertProc. 

genericProc is where most of the application's real implementation resides. genericProc is 
called, for example, to open an icon, to produce a property sheet for an icon, to drop 
something on an icon, etc. See GenericProc. 



SmaliPictureProc: type m procedure [ 
data: OataHandle 4-nil, 
type: NSFiie.Type ^ ignorelype, 
normaiOrReference: PictureState] 
RETURNS [smallPicture: xstring.Character]; 
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PictureState: type » { garbage, normal, highlighted, ghost, 
reference, referenceHighiighted }; 

IgnoreType: NSFii«.Type • last[long cardinal]; 

The SmailPictureProc should return a character for the application, which should be 
obtained by passing a 13xl3-bit icon picture to SimpteT«xtFont.AddC)lentDefinedCharacter. 
This character is used when the file is inside a folder. normalOrReference will be either 
normal or reference, and the appropriate small picture should be returned. The 
SmailPictureProc should try to use the type parameter first if it is not Contain««.ignoreType. 
If it is ignoreType, the SmailPictureProc should use the data parameter. This change is 
necessary for allowing the reference icon application to work properly. Fine Point: The picture 
for normalOrRflference = reference/referenceHIghlighted will not normally be used by the folder 
application directly, but rather would be used by a generic reference icon application. 

Data: type ■ record [ 

reference: NSFii«.Ref erence NSFiie.nullRef erence ]; 

OataHandle: TYPE ■ long pointer to Data; 

nuilData:Data; 

Data uniquely identifies a file. An application needs to distinguish one file from another. 
Two documents may be the same file type, but probably have different names and different 
contents. Whenever an application's PictureProc or GenericProc or 
Implementation.convertProc is called, the particular file being operated on by the user is 
passed to the procedure through the DataHandle parameter. An NSFHe.Reference uniquely 
identifies a particular file and allows the application to utilize various NSFIIe file-accessing 
procedures for manipulating the file, null Data is a constant that should be used to 
represent a null Contain««.Data. 

GenericProc: type ■ procedure ( 

atom: Atom.ATOM, 

data: DataHandle, 
changeProc:ChangeProc nil, 
changeProcData: long pointers- nil] 
returns [long unspecified]; 

A GenericProc is a procedure supplied by an application as part of an Implementation. The 
GenericProc will be called to perform one of several operations that a user can invoke, atom 
tells the GenericProc what operation to perform. For example, when the user selects an 
icon and presses the OPEN key, the application's GenericProc is called with an atom of 
Open. 

data identifies the particular NSFile to be operated on. The NSFile's file type will be the one 
for which this application has registered its Implementation. 

A GenericProc must return a value. The type of the return value depends on the atom 
passed in. Some atoms, their meaning to the GenericProc, and the expected return values 
are as follows: 

Atom Return Value and Meaning 
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Can YouTakeSelection long pointer to boolean 

If the application is willing to have the current selection 
dropped onto it, the GenericProc should return true. This occurs 
when the user has selected something, pressed COPY or MOVE, 
and then selected one of this application's files. While the user 
has the mouse button down, the cursor changes to a question 
mark if the GenericProc returns false; otherwise, the cursor 
stays the same and the icon picture highlights. This operation 
should be efficient and usually involves calling 
S«i«€tion.CanYouConvert or Stti«€tion.HowHard or Seittction.Query 
to determine what S«lection.Targets the selected object can be 
converted to. For example, the printing application's 
GenericProc returns true if the current selection can be 
converted to an Interpress Master. 
The diangeProc need not be called for this atom. 

Can YouTakeSelectionBackground long pointer to boolean 

This is only called after the GenericProc returns true to 
CanYouTakeSeiection. This atom asks if the GenericProc can 
support a background take using an encapsulated selection. 
The CanYouTakeSeiection call is always called first to find out 
if the selection type is one that the GenericProc can take. The 
CanYouTakeSelectionBackground atom need not query the 
selection again; all that's needed is to return true if it supports 
background take operations. If this atom returns true, the 
caller will call s«iectionX. Encapsulate (see the Selection 
chapter), do a fork, and call the GenericProc with 
TakeSelectionBackground or TakeSelectionCopyBackground. 
If this atom returns false, the client will not fork and will do a 
foreground TakeSelection or TakeSelectionCopy. 
The changeProc need not be called for this atom. 

FreeMenu None 

The application should free the menu that was created for the 
Menu atom, if any. The MenuOata.MenuHandte that was 
returned for the Menu atom will be passed as the 
changeProcOata. This atom will not be passed to the 
GenericProc if the Menu atom returned NIL. The changeProc 
need not be called for this atom. 

MenuData.MenuHandie 

The application may create a menu. The menu will displayed 
by the system as a popup menu. This atom is passed when the 
user requests a popup menu for an icon, e.g. by pressing both 
mouse buttons simultaneously while the mouse is over an icon 
on the desktop or in a container window. If the application 
returns a menu, then it should be prepared to free the menu 
when the FreeMenu atom is passed to the GenericProc. The 
changeProc need not be called for this atom. 

StarWindowShelLHandle 

The application should create a StarWindowSheil. Usually, the 
content displayed in the StarWindowSheil will be derived from 
the contents of the file. For example, the ViewPoint document 



Menu 



Open 
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TakeSeiectionBackground 



TakeSelectionCopy 



TakeSelectionCopyBackground 



editor application displays the text and graphics contained in 
the file, thus making the file ready for viewing and/or editing. 

StarWindowShttli-Handle 

The application should create a PropertySheet. Usually, the 
properties shown reflect some attributes of the file. For 
example, the Folder property sheet shows the name of the 
folder, how it is sorted, and how many objects it contains. These 
properties are all NSFile attributes of the file. 

LONG POINTER TO BOOLEAN 

The action performed for this atom is highly dependent on the 
particular application. This atom is passed when the user has 
selected something, pressed MOVE, then selected one of this 
application's files. For some applications, this means the 
selected object should be moved into this application; for 
example, the Folder application converts the selected object to a 
file and adds the file to the folder. For other applications, this 
means the selected object should be operated on in some 
application-specific fashion; for example, the printing 
application converts the selected object to an Interpress Master 
(fUe or stream) and then sends the master to a printer. The 
GenertcProc should return true if the operation was successful, 
FALSE otherwise. 

LONG POINTER TO BOOLEAN 

The same as TakeSelection except that the GenericProc is 
called from a background process so the GenericProc must use 
an encapsulated selection rather than the user's selection. To 
get the encapsulated selection, the GenericProc should raise the 
signal GetContaineeOataContext which will will be caught by 
the caller and will resume with a long pointer to 
s«i«ctionX.Saved (see the Selection chapter). The GenericProc 
can then call S«ta€tionX.ConvertX to get the value of the selection 
followed by S«l«ction.CopyOrMove. The client should always 
call the GenericProc with CanYouTakeSeiection-Background 
before calling with this atom. 

LONG POINTER TO BOOLEAN 

This atom has the same meaning as TakeSelection, except it 
corresponds to the COPY key being pressed rather than MOVE. 
Again, the meaning of this is highly application dependent. 

LONG POINTER TO BOOLEAN 

This atom has the same meaning as TakeSelectionCopy, except 
it corresponds to the COPY key being pressed rather than .MOVE. 
See TakeSeiectionBackground for more details. 



The changeProc must always be called, passing in changeProcOata and an indication of 
which NSFile attributes have changed, if any. If the execution of the GenericProc causes 
any change to the NSFile's attributes, calling the changeProc allows containers (such as 
Desktop, Folders) to update the display to reflect the changes. For example, when the atom 
is Props, the GenericProc must save the changeProc and return the starWindowSheil. Handle 
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for the property sheet. Then later, if the user changes the file's name, for example, the 
application's PropertyShe«t.MenultemProc gets control when the user is done and must then 
retrieve the changeProc and call it. (See the section on Usage/Examples for more detail.) 

If the client's GenericProc is called with an atom that it does not recognize, it should call 
the previous GenericProc (using the old Impiementation that was returned when it called 
Contain««.Setlmpiamentation). The original system-supplied GenericProc acts to backstop 
all possible atoms. 

ChangeProc: type • procedure [ 
changeProcOata: long pointer *~ nil, ^ 
data:DataHandie, 

changedAttributes: NSFii«.Selections H 
noChanges: boolean <- false]; 

A ChangeProc is a callback procedure that is passed to a GenericProc. It must always be 
called by the client regardless of whether an attribute of the Hie being operated has 
changed. The reason for always calling the changeProc is to allow deallocation of the 
ChangeProcOata. The noChanges boolean indicates the effect on the relevant file's 
attributes. The changeProcOata parameter must be correctly supplied even for the 
noChanges = true case. This is used, for example, when the user changes the name of a file 
by using a property sheet When the property sheet is taken down, the application changes 
the file's name and the ChangeProc that was passed to the GenericProc must then be called 
by the application. (See more detail in the section on Usage/Examples). 

PictureProc: TYPE « procedure [ 
data:OataHandle, 
window: window.Handle, 
box: Window.BOX, 
old, new: PictureState ]; 

PictureState: type ■ {garbage, normal, highlighted, ghost, reference, referenceHighiighted}; 

A PictureProc is a procedure supplied by an application as part of an Implementation. The 
PictureProc is called whenever the desktop implementation needs to have the application's 
icon picture repainted or painted differently. 

data identifies the particular NSFiie whose picture should be painted. The NSFlle's file type 
will be the one for which this application has registered its Implementation. Even though 
all files of the same tjrpe will have the same PictureProc and therefore the same-shaped 
picture, each picture will differ because the name of the NSFiie is often displayed on the 
picture. An application's PictureProc can obtain an NSFile's name by using NSFii« operations, 
but may more easily obtain it using Containee.GetCachedName. This is one of the primary 
intended uses for GetCachedName. (See the section on Attribute Cache). 

window and box should be passed to any display procedures used to paint the icon picture, 
such as Olsplay.Bitmap and SimpteTextoisplay.StringintoWindow. 

The old and new arguments describe the current and desired states of the icon picture, 
garbage is the unknown state. PictureProc will be called with new « garbage before 
moving or otherwise altering the icon; this lets an application remember an icon's 
placement. The application can thus continually update the icon (for example, to represent 
time-of-day) or can force a repaint by using window.lnvalidate (to change the shape of an 
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InBasket icon, for example), normal is the picture displayed when the icon is not selected, 
highlighted is the picture displayed when the icon is selected, ghost is the picture 
displayed when the icon is currently open, reference is the picture displayed to represent a 
remote file. referenceHighlighted is the highlighted version of reference. The desktop 
implementation will never use these last two states, but a generic reference icon 
application might. 



DefaultFiieConvertProc: s«i«<tion.ConvertProc; 



OefauitFileConvertProc is a s«i«ction.ConvertProc that knows how to convert to 
S«i«ction.Targets of file and fileType. OefauitFileConvertProc should be called from an 
application's Implementation.convertProc for these targets, or should be provided as the 
application's Implementation.convertProc if the application has no convertProc of its own. 
No file-backed application's convertProc should need to worry about these target types. 

GetContaineeOataContext: signal [dataHandle:OataHandle] 
RETURNS [context: long pointer]; 

This allows the client to pass some client data to the GenericProc. For certain atoms that 
the GenericProc and its clients agree upon, the GenericProc may raise this signal. The 
caller should catch the signal and resume with a long pointer to some mutually agreed 
upon data. One example of where this is used is in doing a background take. See the 
comments on the TakeSeiectlonBackground atom for how it uses 
GetContaineeOataContext. Fine point: G«tContain««OataContext is defined in Contain«eExtra. 

17.2.2 Items for Application Coosumers 

These items would not ordinarily be used by an application implementation (provider), but 
rather by a consumer such as the Desktop or Folder implementation. 

Getlmplementation: procedure [NSFii«.Type] returns [Implementation]; 

Getlmplementation returns the current Implementation for a particular file type. 

17.2.3 Defaultlmplementation 

Contains supports a single global default Implementation. This default Implementation is 
used when the user operates on an NSFile for which no Implementation has yet been 
registered. 

GetOefaultlmplementation: procedure returns [Implementation]; 

GetOefaultlmptementation returns the current default Implementation. 

SetOefaultlmplementation: procedure [Implementation] 
returns [ Implementation]; 



The default implementation provides a dummy display and appropriate "Sorry, Desktop is 
Unable to Open That Object" complaints in the absence of a particular implementation. 
Most clients will not call SetOefaultlmplementation. 
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17.2.4 Attribute Cache 

Clients often want to use several common NSFito^ttributes, but it is awkward to pass the 
attributes around in calls, because the attributes are long, of variable length, and 
frequently not needed by the called routine. Therefore, Containee provides a cache 
mechanism that can remember and supply popular attributes. Currently, the name and 
file type attributes are supported, as well as the run-time busy attribute. Containee 
decouples the management of in-memory copies of a file's name from parameter-passing 
arrangements. 

GetCachedBusy: procedure [data: ContainM.OataHandie] returns [busy: boolean]; 

Returns true if the file was made busy with SetCachedBusy, false otherwise. 'Busyiness' is 
not actually an attribute stored with the file, but is actually a run-time bit maintained by 
Containee. See the Busylcon chapter for a general interface to busy icons. Fine point: 
G«tCadi«dBusy is defined in Contain««Extra. 



GetCachedName: procedure [data:DataHandle] 
RETURNS [name: xstring-ReaderBody, ticket:Ticket]; 

GetCachedNameX: procedure [ 
data:OataHandle, 

handle: NSFii«.Handle 4- NSFiie.nuilHandle, 
session: NSFit«.Session 4-NSFii«.nuilSession] 
RETURNS [name: xstring.ReaderBody, ticket:Tlci(et]; 

GetCaciiedName returns the name attribute of the NSFile referred to by data. If the name 
is not in the cache, it is looked up and added to the cache, ticket must be returned (by using 
Return Ticket) when the client is through with the name. The ticket is to prevent one client 
from changing the name while another is looking at it. GetCachedNameX is identical to 
GeKachedName, but takes a handle and a session. If handle is non-null, Containee will 
use the handle instead of opening its own handle if it needs to fetch attributes from the file, 
session is used for any filing operations including opening the file if necessary, which is 
done if handle is nullHandle. handle and session are needed if the client has data (or its 
parent) open in a session other than the default session. Fine point: GetCachedNameX is defined 
in ContaineeExtra. 



GetCachedType: procedure [data:OataHandle] 
RETURNS [type:NSFiie.Type]; 

GeKachedTypeX: procedure [ 
data:OataHandle, 

handle: NSFiie.Handle 4-NSFiie.nullHandle, 
session: NSFUe.Session «-NSFne.nuilSession] 
RETURNS [type:NSFiie.Type]; 

GetCachedType returns the type attribute of the NSFlie referred to by data. If the type is 
not in the cache, it is looked up and added to the cache. GetCachedTypeX is identical to 
GetCachedName, but takes a handle and a session. If handle is non-null, Containee will 
use the handle instead of opening its own handle if it needs to fetch attributes from the file, 
session is used for any filing operations including opening the file if necessary, which is 
done if handle is nullHandle. handle and session are needed if the client has data (or its 
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parent) open in a session other than the default session Fine point: GetCachedNameX is defined in 
ContaineeExtra. Fine point: GetCachedTypeX is defined in ContaineeExtra. 

invaiidateCache: procedure [data:OataHandlel ; 

InvalidateCache clears any information about the NSFile from the cache. It is typically 
called when the attributes of an NSFile are changed by an application. An application 
rarely needs to call InvalidateCache, because calling the ChangeProc takes care of it. 

InvalidateWholeCache: procedure ; 

InvalidateWholeCache clears the entire cache. Information about all files is cleared. 
ReturnTicket: procedure [ticket: Ticket]; 

ReturnTicket should be called after calling GetCachedName, when the client no longer 
needs the string. 

SetCachedBusy: procedure [ 
data: Containee.OataHandle, 
busy: boolean]; 

Mark the file ''busy." The status of the file can later be queried with GetCachedBusy. 
"Busyiness' is not an attribute stored with the file, but is a run-time status maintained by 
Containee. For a more general busy icon interface, see the Busylcon chapter. Fine point: 
S«tCach«dBusy is definedin ContaineeExtra. 

SetCachedName: procedure [data:OataHandle, newName: xstring.Reader]; 

SetCachedName allows a client to change a cached name. Care should be taken to keep the 
filed name consistent with the cached name. An application rarely needs to call 
InvaiidateCache, because calling the ChangeProc takes care of it. 

SetCachedType: procedure [data:DataHandle, newType:NSFiie.Type]; 

SetCachedType allows a client to change a cached type. Care should be taken to keep the 
filed type consistent with the cached type. 

Ticket: TypE[2]; 

A Ticket is returned when GetCachedName is called. When the client is done using the 
cached name, the ticket must be returned by calling ReturnTicket. This is to prevent one 
client from changing the name while another is looking at it. 
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17.3 Errors and Signals 

Error: error [msg: xstrtng.Reader <-nil, error: error nil, 
errorOata: long pointer to uNSPeaFiED 4- nil]; 

Signal: signal [msg: xstring.Reader 4-nil, erroR errors- nil, 
errorData: long pointer to UNSPEapiEO ^ nil]; 

An application's GenericProc (and PictureProc and ConvertProc) should never assume that 
it has been called by a desktop, and therefore should never call such facilities as 
Attentlon.Post or UMrT«nninal.BtinkOispiay. (The application might be called by CUSP, for 
example.) Rather, the application should raise Contain««.Error or Signal with an appropriate 
message. Containea will not catch these errors. The caller of the application's GenericProc 
should catch them and do the appropriate thing. In the typical case, the ViewPoint desktop 
calls the application's GenericProc; it catches the error and calls Attsntion.Post with the 
passed message. CUSP could catch the error and log the message in a log file. 

msg is the message to display to the user, error is the actual lower-level error that occurred 
that caused Error or Signal to be raised. errorData points to any additional data that 
accompanied the lower-level error. 

17.4 Usage/Examples 

17.4.1 Sample Containee 

The folder application is used as an example of a simple application that implements a 
particular file type. 

— Constants and global data 

folderFileType: NSFii«.Type a . . .; 
oldlmpi: contaifiM.lmplementation 4- []; 

" Contain9€.lmplementation procedures 

FolderGenericProc: Contain««.GenericProc ■ 
< <[atom: AtomJ^TOM, 

data: contain^.DataHandle, 

changeProc: Contain9:ChangeProc i-nil, 

changeProcData: long poihter^ nil} 

RSTIJRNS [long UNSPEaFieD]> > 

begin 

select atom FROM 

open ■ > RETURN [Mal(eFolder[data, changeProc, changeProcData] ]; 

props ■ > RETURN [Mal(ePropertySheet[data, changeProc, changeProcData]]; 

canYouTalceSeiection ■ > return [ if CanlTal(e[changeProc. changeProcData] 

THEN ©true else @faise]; 
canYouTaiceSeiectionBacicground ■ > return [ @true] 
talceSelection, takeSelectionBacicground ■ > 
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RETURN [ 

iFTakefdata, move, changeProc, changeProcData, 
atom ■ takeSelectionCopyBackground] 
THEN ©true ELSE @false ]; 
takeSeiectionCopy, takeSelectionCopyBackground ■ > 

RETURN [ 

ipTake[data, copy, changeProc, changeProcOata, 

atom ■ takeSelectionCopyBackground ] 
THEN Otrue ELSE @faise ]; 
menu • > 
BEGIN 

run: xstring.ReaderBody 4-xstring.FromSTRING [''AitOpen"L]; 
name: xstring.ReaderBody 4-xstring.FromSTRING [*'Folder''L]; 
title: M«nuOata.ltemHandie 4-M«nuOata.Createltem( 

zone: nil. name: ©name, proc: nil]; 
items: array[0..1) of M«nuOata.ltemHandle 4- [ 

M«nuOata.Createitem[zone: nil, name: @run, proc: AltOpen]]; 
menu: ManuOata.MenuHandle 4— MenuOata.CreateMenuC 

zone: nil, title: title, array: OESCRiPTOR[items]]; 
RETURN [menu]; 
end; 
f reeMenu ■ > 

BEGIN 

menu: McnuOata.MenuHandle *-~ changeProcOata; 
ManuData.OestroyMenu [NIL, menu]; 
RETURN[menu]; 
end; 

endcase ■ > return [ 

oidlmpi.genericProc [atom, data, changeProc, changeProcData] ]; 

end; 

AitOpen: MenuOata.MenuProc ■ {...}; 

CanlTake: procedure [ 

changeProc: Contain««.ChangeProc 4-nil, 
changeProcOata: long pointer nil] 
RETURNS [yes: boolean] ■ { 

< < Use Selection.CanYouConvert to see if the current selection can convert to a 
file. If so, then return TRUE, else FALSE. > > 

}; 

MakeFolder: procedure [ 
data: Containae.OataHandle, 
changeProc: Containea.ChangeProc 4-NiL, 
changeProcOata: long pointer 4- nil] 

RETURNS [shell: StarWlndowShelLHandle] ■ { 

< < Create and return a StarWindowShell containing a list of the files in this folder. 
Use FileContainerShelLCreate. >> 

}; 

MakePropertySheet: procedure [ 
data: Containee.OataHandle, 
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changeProc: Containee.ChangeProc 4~nil, 
changeProcData: long pointer nil] 

RETURNS [psheet: StarWindowSh«II.Handle] ■ { 

< < Create and return a property sheet using PropertySheetCreate, > > 

}; 

Take: procedure [ 

data: ContainM.OataHandle, 
copyOrMove: s«i«ction.CopyOrMove, 
changeProc: Conuin«e.ChangeProc 4~nil, 
changeProcData: long pointer 4- nil] 

RETURNS [ok: boolean] m { 

v: selection. Value; 

manager: long pointer to S6iection.Saved 4- @mgr; 
mgr: Selection. Saved s«iectionX.nul I Manager; >> 
IF background then 

manager 4- contain«eExtra.GetContaineeOataContext[data]; 
< < If this is a bacicground talce, get the encasuiated selection 

Convert the current selection to a file using SelectionXXonvert or 
SelectionX.Enumerate with mgr, and copy or move that file into this folder. > > 

}; 

Initialization procedures 

InitAtoms: procedure a { 

open «-Atom.MakeAtom('*Open"L]; 
props <-Atoin.MakeAtom["Props'*L]; 

canVouTakeSelection 4^Atom.MakeAtom["CanYouTakeSelection"L]; 

canYouTakeSelectionBackground 4- 

Atom.MakeAtom[**CanyouTakeSeiectionBackground''L]; 

takeSeiection *~ Atom.MakeAtom[**TakeSeiection"L]; 

takeSeiectionCopy Atom.MakeAtom['*TakeSelectionCopy "L]; 

takeSeiectionCopyBackground 4- 

Atom.lVlakeAtom["TakeSelectionCopyBackground'*L]; 

menu 4-Atom.MakeAtom[*'Menu'*L]; 

f reeMenu 4- Atom.MakeAtom[**FreeMenu "L] ; 

}; 

Setlmplementation: procedure » { 

newimpi: Containee.lmplementation 4-Containee.Getlmpiementation [ 

foiderFilelype]; 
newlmpl.genericProc FolderGenericProc; 
oidlmpi 4-Containee.Setlmplementation [folderFileType, newimpi ]; 

}; 

— Mainline code 

InitAtomsd; 

SetlmplementationQ; 
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17.4.2 ChangeProc example 

The folder property sheet is used to demonstrate a callback to a ChangeProc. 

OataObject: type ■ record [ 
fh: NSFii«.Handler 

ChangeProc: ContainM.ChangeProc «-nil, 
changeProcData: long pointer *- nil]; 

Data: TYPE ■ long pointer to OataObject; 

MakePropertySheet: procedure [ 
data: ContainM.OataHandle, 
ChangeProc: ContainM.ChangeProc 4-nil, 
changeProcOata: long pointer 4- nil] 
RETURNS [pSheetSheil: starWindowSh«il.Handie] » { 

— Pass ChangeProc to Makeltems through clientOata. 

mydata: Data 4- zone.NEW[OataObject <- [ 
fh: NSFile.OpenByReference[@data.reference], 
ChangeProc: changeProc, 
changeProcOata: changeProcOata]]; 

pSheetSheil 4-PropertySh««t.Create [ 
formWindowltems: Makeitems, 
menultemProc: MenuitemProc, 
menultems: [done: true, cancel: true, defaults: true]., 
title: XMessage.Get [...], 
formWindowitemsLayout: OoLayout, 
display: false, 
clientOata: mydata]; 

}; 

Makeltems: Form window. Ma keltemsProc ■ { 

Make property sheet items with calls to FormWindow.MakeXXXitem. 

}; 

MenultemProc: PropertyShe«t.MenuitemProc ■ { 

<< [shell: starwtndowSh9ii.Handle, formWIndow: window.Handle, 

menultem: Prop^rtySh^^LMenultemType, clientOata: lohgpoimter} 

RETURNS [destroy: boolean*- false] > > 
mydata: Oata ■ clientOata; 
SELECT menultem from 

done • > RETURN[destroy: ApplyAnyChanges[formWindow, mydata].ok]; 

cancel « > RETURN[destroy: true]; 

defaults ■ > . . . 

endcase; 
RETURN[destroy: false]; 

}; 
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ApplyAnyChanges: proc [fw: window.Handle, mydata: Data] returns (ok: boolean] ■ { 
" Collect any changes in the property sheet items. 
NSFil«.ChangeAttributes [mydata.fh, ...]; 

BEGIN " Call the changeProc. 

data: contain««.Oata <- [ NSFii«.GetReference [mydata.fh] ]; 
IF mydata.changeProc # nil then 

mydata.changeProc(mydata.changeProcData, @data, changedAttributes]; 
end; 

RETURN [ok: TRUE]; 

}; 

17.4.3 Error and Signal Usage 

Tills client catches an NSFilc.Error and raises ContainM.Error* passing along the error and the 
NSPito.ErrorRecord: 

message: xstring.ReaderBody; 
errorRecord: NSFiie.ErrorRecord; 
signal : —GENERIC" signal nil; 
file 4*NSFii«.0penByReference [reference: ... ! 

NSFii«.ErrQr • > { 
errorRecord 4- error; 
signal 4- LOOPHOLE[NSFii«.Error, signal]; 
GOTO ErrorExit}]; 
< < Operate on the file. > > 
NSFiie.Ciose[fiie]; 

EXITS 

ErrorExit ■ > { 
message xstring.FromSTRtNG(''NSFii«.Error'*L]; 

Contain««.Error [msg: ©message, error: signal, errorData: ©errorRecord]; 
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ChangeProc: type 


7 


Data: type 


4 


DataHandle: type 


4 


DefaultFileConvertProc: s«i«ction.ConvertProc 


8 


Error: ERROR 


11 


GenericProc: type 
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GatCachedBusy: procedure 
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GetCachedName: procedure 
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GetCachedNameX: procedure 
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GetCachedType: procedure 
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GetCachedTypeX: procedure 


10 


GetContaineeDataContext: signal 
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4 


Implementation: type 
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IhvalldateCache: procedure 


10 


InvaiidateWholeCache: procedure 


10 


nullData:Oata 


4 


PtctureProc: type 


7 


PIctureState: type. 


4.7 


ReturnTicket: procedure 


10 


SetCachedBusy: procedure 


10 


SetCachedName: procedure 


10 


SetCachedType: procedure 


10 


SetDef aultl mplementation : procedure 


9 


Setlmplementation: procedure 


2 


Signal: SIGNAL 


11 


SmallPictureProc:TYPE 


3 


Ticket: type 
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18.1 Overview 

The ContainerCache interface provides the writer of a ContainerSource with a cache for 
the container's items. ContainerCache supports storing strings and client data with each 
item. 

18.2 Interface Items 

18.2.1 Cache Allocation and Management 

Handle: type « long pointer to Object; 
Object: type; 

AllocateCache2: PROCEDURE [useProcessAbort: boolean <-* true] returns [Handle]; 

AllocateCache2 returns a handle on a cache that can be filled with BeginFIII. The client 
should call ResetCache before calling BeginFiil. useProcessAbort indicates whether 
Process.Abort should be raised by ContainerCache when the fill process is aborted-for 
example, when the cache is destroyed while still filling. It is intended to accommodate 
clients that cannot properly handle ABORTED. AllocateCache2 is actually in 
ContainerCacheExtra2. mesa. 

AilocateCache: procedure returns [Handle]; 

AllocateCache returns a handle on a cache that can be filled with BeginFiil. The client 
should call ResetCache before calling BeginFiil. 

GetLength: procedure [cache: Handle] returns [cacheLength: cardinal]; 

GetLength returns the number of items in the cache. GetLength is actually in 
ContainerCacheExtra. mesa. 

ResetCache: procedure [Handle]; 
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ResetCache clears the cache so that, for example, the cache can be refilled by calling 
BeginFill. 



FreeCache: procedure [Handle]; 
Frees the resources used by a cache. 

1SJL2 FUling the Cache 

The client initially fills a cache with items by calling BeginFiil with a FiiiProc. The FillProc 
adds items to the cache by repeatedly calling Appendltem. 

FiiiProc: type « procedure [cache: Handle] 

RETURNS [errored: BOOLEAN 4- FALSE]; 

The client provides a FillProc to the BeginFiil procedure. The FiiiProc should fill the cache 
by using Appendltem. errored is an indication of whether an error occurred during the 
filling of the cache (errored « true). 

BeginFiil: procedure [ 
cache: Handle, 
fiilProc: FiiiProc. 
clients: long pointer, 

fork: BOOLEAN 4>TRUE ]; 

Clients: procedure [cache: Handle] 
RETURNS [clients: long pointer]; 

BeginFiil begins filling the cache. fiilProc is called to add items to the cache. If fork is true, 
then fiilProc is forked as a separate process, clients is stored with the cache and may be 
retrieved by calling Clients. 

CacheFiilStatus: type « {no, inProgress, inProgressPendingAbort, 
inProgressPendingJoin, yes, yesWithError, spare }; 

StatusOfFiil: procedure [cache: Handle] 
RETURNS [CacheFiilStatus]; 

StatusOfFiil returns the current status of the cache fill, yes indicates that the fill has 
successfully completed; no means the cache has not been filled yet; inProgress indicates 
that the fill is running right now. inProgressPendingAbort indicates that an abort has 
been received but the fiilProc has not yet returned. inProgressPendingJoln, yesWIthError, 
and spare are not currently used. 

18.2.3 Item Operations 

ItemHandle: TYPE ■ long pointer to itemObject: 
ItemObject: type.- 
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AddData: type =» recoro[ 

dientData: long pointer, - TO ARRAY [0..0) OF WORD 
dientDataCount: cardinal, 

dientStrings: long descriptor for array op xstring.ReaderBody]; 

An AddData record is passed to the Appendltem, Insertltem, and Replaceltem procedures. 
dientOata should contain any data that the client wants to cache with the item, usually 
some type of reference to the actual item. dientDataCount is the size (in words) of the 
dientData. dientData is copied into the cache; therefore the dientData should contain no 
pointers to other data. diantStrings should contain the strings to be displayed for the item. 
dientStrings are also copied into the cache, alloMring the client to free them. 

The standard use of dientStrings is to implement the ContaincrSourct.StringOfltemProc, 

which can be accessed efEiciently by using ItemNthString. (See the section on item content 
operations for more details on accessing the contents of items.) Caution: There are 
restrictions on the total length of an item (strings plus client data) that may be added to a 
cache. Currently, no item should he longer than 512 bytes. 

Appendltem: procedure [ 
cache: Handle, 
addData: AddData] 
RETURNS [handie:ltemHandle]; 

Appendltem appends an item to the end of cache. It is usually called repeatedly from 
within a FillProc. handle is a pointer that can be used to access the new item. 

DeieteNltems: procedure [ 
cache: Handle, 
item: cardinal, 
nitems: cardinal <- i ]; 

DeieteNltems deletes one or more consecutive items from cache, starting at item. Fine point: 
Because the cache ia maintained as a contiguoua string of bits, this operation is likely to be slow compared to 
Appendltem and GetNthltem. 

GetNthltem: procedure [cache: Handle, n: cardinal] 
RETURNS [ItemHandle]; 

GetNthltem returns the nth item in cache. The items are numbered from zero. It returns nil 
if no such item exists. The ItemHandle returned is not guaranteed to be valid after any 
operation that modifies the cache (DeieteNltems, Insertttem, Replaceltem). If the cache 
status is inProgress (if someone is in the process of filling the cache), GetNthltem does not 
return until the nth item has been appended to the cache or until the fill is complete. 
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Insertltem: procedure [ 
cache: Handle, 
before: cardinal, 
addData: AddData] 
RETURNS [handle: ItemHandle]; 

insertltem inserts an item in cache. The new item is inserted before the item before. Note 
that all the items after this item will be renumbered. Fine point: Becauae the cache is maintained as 
a contigvious string of bits, this operation is likely to be slow compared to Appendltem and <3«tNthltem . 

Replaceltem: procedure [ 
cache: Handle, 
Item: cardinal, 
addData: AddData] 
RETURNS [handle: ItemHandle]; 

Replaceltem replaces the contents of item in cache with the information in addData. Fine 

point: This operation is implemented as D«l«teNlt«ms followed by InsertKem, and so is likely to be slow compared 
to Appandltem and GetNthKam. 

18.2.4 Item Content Operations 

Itemlndex: procedure [item: ItemHandle] returns [index: cardinal]; 

Given the handle item, ItemI ndex returns its i ndex in the cache. 

ItemClients: procedure [item: ItemHandle] returns [clientData: long pointer]; 

Returns the client data associated with item. If the client data passed in was NIL, 
clientData is NIL 

itemClientsLength: procedure [item: ItemHandle] returns [dataLength: cardinal]; 
Returns the length of the client data passed in with item. 
ItemStringCount: procedure [item: ItemHandle] returns [strings: cardinal]; 
Returns the number of client strings associated with item. 

ItemNthString: procedure [item: ItemHandle, n: cardinal] returns [xstring.ReaderBody]; 

Returns the nth client string associated with item. This operation can be used to 
implement a ContainerSource.StringOfltemProc . 

18w2.5 Marking Items in the Cache 

Whenever items are deleted or inserted in a ContainerCache, all the items are renumbered. 
This allows a client to keep track of items by marking them. ContainerCache keeps track of 
the marked items across any changes to the cache. A mark is a handle on a cache item that 
tracks the item when the item number changes. This facility is handy for 
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container source implementations that use ContainerCache and want to perform all the 
various combinations of moving and copying items within the source. 

Mark: type » long pointer to MarkObject; 
MarkObject: type; 

SetMark: procedure [ 

cache: ContainerCache.Handle, index: cardinal] 
RETURNS [mark: Mark]; 
~ set a mark at index 

IndexFromMark: procedure [mark: Mark] 
RETURNS [index: cardinal]; 
— get the current value of this mark 

MoveMark: procedure [mark: Mark, newlndex: cardinal]; 
" allows the resetting of a mark without using a new one 

FreeMark: procedure [mark: Mark]; 
'•mark no longer needed 

18.3 Usage/Examples 

After the client allocates a cache, the client starts filling the cache by calling BeginFill with 
a FiliProc. BeginFill immediieitely calls the FillProc. Inside the FillProc, the client usually 
does some kind of enumeration on the source backing (for example, if the source is backed 
by files, the client does an NSFite.List). For each item enumerated by the FillProc, the client 
builds the required strings for that item and then passes the strings along with any item 
data to Appenditem. The item data is usually some information that is needed to identify 
the item uniquely (for the file example, this might be a file ID). This process continues 
until all the items in the source have been enumerated, at which time the FillProc returns. 

The call to BeginFill may indicate that the FillProc should be forked into a separate process. 
Tills allows the enumeration of the source's items to go on in the background, which is an 
advantage if the source has a large number of items. If the source is being displayed in a 
ContainerWindow while this background Gil is taking place, the window displays each 
new item as it is appended to the cache. Fine point: ContainerWindow can display the items as tliey are 
added because G«tNthlt«m will wait during the filling of the cache until the requested item is in the cache instead 
of returning with an indication that the requested item is not available. 

Once the cache has been created, operations on the container source that owns the cache 
may cause items in the cache to become invalid. One way to bring the cache back into 
synch is to invoke BeginFill and rebuild the cache. If reenumerating the items in the source 
is expensive, items in the cache can be updated with the operations OeleteNltems, 
Insertltem, and Replaceltem. The disadvantage of these operations is that they may cause 
performance degradation. Fine Point: The current implementation tries to maintain the cache as a 
contiguous series of strings of bits to minimize swapping. Using these operations may move large amounts of data 
around or fragment the cache data. If a large number of changes are to be made, it may pay to rebuild the cache. 
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Use of ContainerCache may not always be appropriate. In some cases, the structure of 
items in a source may be simple enough that a simple data structure may stifElce to hold all 
the information necessary to respond to source operations. 

18J3.1 Example of ContainerCache Use 

The following example is taken from the implementation of FileContainerSource. It gives 
an example FillProc that uses Appendltem to build the cache. 

ReaderSeq: me > record [sequence length: cardinal op xstring.ReaderBody]; 

ReaderSeqPtr: TYPE « long pointer to R«ad«rS«q; 

WritcrSaq: TYPE > RECORD (SEQUENCE length: CARDINAL OF XString. WriterBody]; 

WrIterSeqPtr: TYPE - long pointer to WriterSeq; 

FillCachelnBackground: Contain«rCache.FillProc « 

< < [cache: Handle] ReWRNS [errored: BOOLEAN ^ FALSE] > > 

BE6IN 

fs: FS4-Cofitain«rCaciM.cnents{cache]; get container source context 
parentHandle: NSPii«.Handie; 

writers: WriterSeqPtr 4-AllocateWriters [fs.columns.length]; 
readers: ReaderSeqPtr *- z.N^ [ReaderSeq[fs.coiumns.length]]; 

Enumerator: Nsni«JVttributesProc « 
begin 

itemData: ItemFileOata; 
addOata: ContainerCa€h«.AddData; 

addData BuildRow [fs, writers, readers, @itemOata, attributes]; 

[] 4- ContainerCache.Appendltem [cache, addData]; 

return; 

end; 

BEGIN 

parentHandle 4- NSFiie.OpenByReference [fs.parentReference]; 
Proccss.SetPriority [Pro<«ss.priorityBackground]; 
NSFiie.List [ directory: parentHandle, proc: Enumerator, 

selections: fs.selections, scope: fs.scope ]; 
NSFito.Close [parentHandle]; 
end; 

Z.FREE [©readers]; 
FreeWriters [writers]; 

return; 
end; 

BuildRow: procedure [ 
fs: FS, 

writers: long pointer to WriterSeq, 
readers: long pointer to ReaderSeq, 
itemData: ItemFileDataHandle, 
attributes: NSFiie-Attributes] 
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RETURNS [addOata: Coiitain«rCa€he.AddData] ■ 

BEGIN 

attr: NSFii«.Attribute; 

ch containM.lmplementation; 

d 4-ContaiiM«.Getlmplementation [attribiitM.type]; 
FOR i: CARDINAL IN [O..fs.columns.len9th) do 
xstring.ClearWriter [@writers[i]]; 

~ Decide the type of column we have (passed in as Coiumn info to 

Pii«ContaiiMrSourct.Create> and call proper format proc to format attribute(s) 
into a string- 
WITH coiumn: fs.columnsn] select from 
attribute ■ > { 

attr 4- AttributeFromAttributeRecord [ 

attributes, column.attr]; 
coiumn.formatProc [ci, attr, @writers(i]];}; 
extendedAttribute ■ > { 

attr 4- ExtendedAttributeFromAttributeRecord ( 

attributes, coiumn.extendedAttr]; 
coiumn.formatProc [ci, attr, @writers[i]];}; 
multipieAttributes ■ > 

edumn.formatProc [d, attributes, @writers(i]]; 
endcase; 

ENDLOOP; 

itemData t [id: attribut«s.fiieiD, type: attributes.type]; 

FOR i: CARDINAL IN [0..writers.iength) DO 

readers[i] <— (xstring.ReaderFromWriter [@writersCi]]) T ; 

ENDLOOP; 

addData [ 

dientData: itemOata, 
dientDataCount: siZE(itemFiieData], 
dientStrings: DESCRiPTOR(readers]]; 

RETURN[addData]; 
end; 
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18.4 Index of Interface Items 
Item 

AddData: typi 
AilocateCache2: procedure 
AilocateCache: procedure 
Appendltem: procedure 
BeginFtil: procedure 
CacheFiilStatus: type 
Clients: procedure 
DeieteNltems: procedure 
FillProc: type 
FreeCache: procedure 
FreeMa rk : procedure 
GetLength: procedure 
GetNthltem: procedure 
Handle: type 

lndexFromMark:PROCEDURE 
Insertltem: procedure 
ItemOients: PRoaouRE 
ItemCientsLength: procedure 
ItemHandle: type 
Itemlndex: procedure 
ItemNthString: procedure 
ItemObject: type 
ItemStringCount: procedure 
Mark:TYPE 
MarkObject:TYPE 
MoveMark:Procedure 

Object: type 
Replaceltem: procedure 
ResetCache: procedure 
SetMark:PROCEDURE 
StatusOfFiil: procedure 
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19.1 Overview 

The Container interfaces (ContainerSource, ContainerWindow, FlieContainerSource, 
FiieContainerSheil, and ContainerCache) provide the services needed to implement an 
application that appears as an ordered list of items to be manipulated by the user. 
Viewpoint Folders are a typical example of such an application. ContainerWindow 
provides the user interface for containers. It displays each item as a list of strings and 
handles selection highlighting, scrolling, and so forth. When a ContainerWindow is 
created, a record of procedures is passed in. ContainerWindow obtains the strings of each 
item by calling one of these procedures. ContainerWindow also performs user operations 
on items, such as open, props, delete, insert, take the current selection, and selection 
conversion by calling other procedures in the record. This record of procedures and their 
implementation is called a container source. A container source can be thought of as a 
supply (source) of items for a ContainerWindow. A container source is responsible for 
implementing container source operations on its underlying representation of the items in 
the source. 

The ContainerSource interface contains the procedure types that make up the record of 
procedures that a container source must implement. These procedure definitions 
encompass all the operations that a source of items must be able to perform. 
ContainerSource also provides a place to save data specific to a particular container source. 

The procedure types defined by ContainerSource fall into three categories: 

• ActOnProc, CanYouTaiceProc, GetLengtliProc, and TaiceProc are operations on the 
source as a whole. 

• ConvertltemProc, DeleteitemsProc, ItemGenericProc, and StringOfltemProc are 

operations on the individual items within the source. 

• SetGlobalChangeProcProc, GetGiobalChangeProcProc, IsBusyProc, SetBusyProc, 
SetMarkProc, FreeMarkProc, IndexFromlVlarkProc, and IVIoveOrCreateMarkProc are 
housekeeping kinds of operations that support background (concurrent) move and 
copy operations within a source. 

Note that the items in a container must exhibit behavior similar to the behavior defined by 
the Containee interface, such as open, props, take selection, convert. However, also note 
that the Containee interface defines the behavior of NSFiles, whereas ContainerSource is 
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totally independent of NSFile. The items in a container may be backed by anything. The 
FtieContainerSource interface is an example of a container source that is backed by 
NSFiles. The ViewPoint Directory application contains examples of container sources that 
are backed by Clearinghouse entries (such as the Filing and Printing dividers) and by 
simple strings in virtual memory (such as a domain divider). 

The ContainerCache interface provides a mechanism for caching the strings and item- 
specific data for the items in a container source. The implementor of a container source 
might find ContainerCache to be handy. 

19.2 Interface Items 

19^1 Handle, Procedures, and ProceduresObject 

Handle: type « long pointer to Procedures; 

Procedures: type « long pointer to ProceduresObject; 

ProceduresObject: type « record [ 
actOn: ActOnProc, 
canYouTake: CanYouTakeProc, 
columnCount: ColumnCountProc, 
convertltem: ConvertltemProc, 
deieteltems: DeleteitemsProc, 
getLength: GetLengthProc, 
itemGeneric: ItemGenericProCr 
stringOfltem: StringOfltemProc, 
take: TakeProc]; 

ContainerSourceExtra.Procedures: TYPE > 

LONG POINTER TO ContainerSourceExtra.PrOCeduresObject; 

Contain«rSourc«Extra.PrOCeduresObject: TYPE s RECORD [ 

canYouTakeX: CanYouTakeProcX, 
takeX: TakeProcX, 

setGiobalChangeProc: SetGlobalChangeProcProc, 
getGlobaiChangeProc: GetGlobalChangeProcProc, 
isBusy: IsBusyProc, 
setBusy: SetBusyProc, 
setMark: SetMarkProc4-NiL, 
freeMark: FreeMarkProc«~NiL, 
indexFromMark: IndexFromMarkProc 4- nil, 
moveOrCreateMark: MoveOrCreateMarkProc 4-nil]; 

Handle identifies a particular container source. Handle is a pointer to a pointer 
(Procedures) to a record of procedures (ProceduresObject) that are implemented by the 
container source. A container source typically EXPORTS a Create procedure that return a 
Handle. This Handle is then passed to Contain«rWindow. Create. Whenever 
ContainerWindow needs the container source to do something, it calls the appropriate 
procedure in the ProceduresObject by using Handle | f , and passing in the Handle. Note: 
Every procedure in the ProceduresObject takes a Handle as its first parameter. Fine Point: 
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Actually, ContainsrWindow will call the INLINE procedures described in the INLINE section, which in turn call 
the procedures in the ProceduresObject. 

Handle is a pointer to a pointer (rather than just a pointer to the ProceduresObject) to 
allow a container source to save data specific to the source. For example, a file-backed 
source would need to keep a pointer to the file. See the section on Usage/Examples for an 
explanation of how this is done. 

Contain«rSourc«Extra.ProceduresObject are extra procedures to support concurency in 
containers. These procedures logically belong in the Contain«rSoHrc«.ProceduresObject. No 
ContainerSourceExtra.Handle is provided because these procedures are auxiliary to the 
mainContaimrSourca.Procedures. A source that supports.these operations will export a Create 
operation that returns a contain«rSourc«. Handle and a Contain«rSourceExtra. Procedures. 
Contain«rWindowExtra4.CreateXX takes both a Contain«rSourct. Handle and a 
ContainerSourceExtra.Procedures. This procedure must be used when the client wants to create 
a container that uses ContainerSourcaExtra.Procedures. 

19.2.2 Procedures That Operate on Individual Items 
Itemlndex: type ■ cardinal: 
nullltem: Itemlndex « ltemlndex.LAST: 

All the procedures that operate on individual items take a Handle and an Itemlndex. An 
Itemlndex is simply a cardinal that uniquely identifies an item in the source. Note: A 
container source is an ordered list of items. An Itemlndex of "n" indicates the "nth" item in 
the source. An Itemlndex of zero corresponds to the first source item. An Itemlndex should 
be thought of as a loose binding: the Index of a particular item may change as a result of 
changes to the source. For example, if an item is deleted, all the items below it will be 
renumbered, nullltem is a constant used to represent no item or unknown item. 

If concurrency is supported within the source, each of the procedures that take an 
Itemlndex as a parameter (StrlngOfltemProc, ItemGenericProc, ConvertitemProc, 
OeleteltemsProc, and TakeProc/TakeProcX) must be able to support a n)etween calls lock" 
on the source that lasts from the time the client calls IndexFromMarkProc to the time one 
of the following procedures is entered. See §19.2.5 for a discussion of IndexFromltem, 
§19.2.6 for a discussion of locking, and the example in §19.4.3 for one way to implement 
this locking. 

StrlngOfltemProc: type « procedure [ 
source: Handle, 
itemlndex: Itemlndex, 
stringlndex: cardinal] 
RETURNS [xstring.ReaderBody]; 

The source's StrlngOfltemProc should return the string stringlndex of item itemlndex in 
source. Each item's display is composed of strings, one for each column of the container 
window. For example, an open Folder shows four columns: the icon picture, the name, the 
size, and the date, stringlndex will be IN [0.. source. columnCount[]) (see also 
ColumnCountProc in the next section). If there is no such item (if itemlndex is greater than 
the number of items in the source, for example), StrlngOfltemProc should raise 
Error[noSuchltem]. StrlngOfltemProc is used extensively and its implementation should 
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be efficient. If the source supports concurrency, this procedure must support the "between 
calls lock'' convention. See §19.2.5 for more details. 

ItemGenericProc: type * procedure [ 
source: Handle, 
itemlndex: itemindex, 
atom: Atom.ATOM, 
changeProc: ChangeProc *- mi, 
changeProcOata: long pointer 4- nil] 

RETURNS [long UNSPEaPlEO]; 

The source's ItemGenericProc is invoked to perform an operation on one of the items in the 
container, itemlndex indicates which item to operate on. The operation is specified by 
atom. Some of the typical atoms are: Open, Props, CanYouTakeSelection, TakeSelection, 
TakeSelectionCopy. This procedure is just like the genericProc that a 
Contain««.lmplementation must provide, see the Containee interface for a complete 
description of the atoms and their return values. changeProc must be called if the 
ItemGenericProc causes the source to change. changeProc and changeProcOata are 
described in more detail below in the section on changeProc tjrpes. 

If the source supports concurrency, this procedure must support the '^between calls lock" 
convention. See §19.2.5 for more details. 



ConvertltemProc: type * procedure [ 
source: Handle, 
itemlndex: Itemlndex, 

n: CARDINAL 

target: s«iection.Target, 
zone: uncolntedzone, 

info: Sei«ction.Conversionlnf o 4- [convertH] « • 
changeProc: ChangeProc 4-nil, 
changeProcOata: long pointer 4- nil] 
RETURNS (value: s«i«ction. Value]; 




The source's ConvertltemProc is invoked to convert one or more of the items in source, just 
as if the item was the current selection and s«l«ction.Convert had been called, itemlndex 
indicates the first item to convert, n indicates how many consecutive items to convert, 
target, zone, info, and value are all identical to the parameters for S«lection.ConvertProc 
(see the Selection interface). If n> 1, then info is the enumeration variant; otherwise, it is 
the convert variant. changeProc must be called if the ConvertltemProc causes the source to 
change, for example, when an item is moved out of the source. changeProc and 
changeProcOata are described in more detail In the section on changeProc types. 

If the source supports concurrency, this procedure must support the ''between calls lock" 
convention. See §19.2.5 for more details. 

DeleteitemsProc: type « procedure [ 
source: Handle, 
itemlndex: Itemlndex, 
n: cardinal 4-1, 
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changeProc: ChangeProc 4-nil, 
changeProcOata: long pointer 4- nil]; 

The source's DeieteltemsProc is Invoked to delete consecutive items from source, 
itemlndex is the first item to delete, n is the number of items to delete. changeProc must 
be called if the OeleteltamsProc causes the source to change, that is, if the deletion is 
successful. changeProc and changeProcData are described in more detail in the section on 
changeProc types. 

If the source supports concurrency, this procedure must support the "between calls lock" 
convention. See §19.2.5 for more details. 



19.2.3 Procedures That Operate on the Entire Source 

CoiumnCountProc: type « procedure [ source: Handle] returns [columns: cardinal]; 

The source's CoiumnCountProc should return the number of columns in source, that is, the 
number of strings in each item. Fine point: typically, the number of columns is the same as COUNT 
[ContainerWindow.CoiumnHMdvrsl. 

GetLengthProc: type » procedure [ source: Handle] 

returns [length: CAROiNAL^totalOrPartial : TotalOrPartial total]; 

TotalOrPartial: type « {total, partial}; 

The source's GetLengthProc should return the total number of items currently in the 
source. This operation is performed often and should be efficient. Some container sources 
have indeterminate length until after an initial enumeration has completed (for example, 
clearinghouse enumerations). These sources may return [totaiOrPartial: partial] while the 
initial enumeration is in progress. This lets the ContainerWindow display mechanism 
know that there are more items coming, while giving it some information along the way. 
Once a source knows how many items are in the source, (or for those sources that know 
right from the start how many items are in the source, (such as NSFiie-backed sources), the 
GetLengthProc should return [totaiOrPartial: total].) 

ActOnProc: type * procedure [ source: Handle, action: Action]; 

Action: type = {destroy, relist, sleep, wakeup}; 

The source's ActOnProc is invoked to request some action of the source. Action indicates 
what the source should or can do. 



destroy The term destroy means that the source should destroy itself, 

freeing all storage and releasing all resources associated with the 
container source instance. 

sleep The term sleep means that the source should release whatever 

resources it can without losing information; it is a hint that the 
container source will not be used for a while. 
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wakeup The term wakeup means that the source is going to be used and 

should resume its normal state, undoing whatever was done for 
sleep. 



reList The term reList means that the source should re-enumerate itself 

because its backing store has been changed. 

CanYouTakeProc type > procedure ( 
source: Handle, 

selection: s«i«ction.ConvertProc 4-nil] 
RETURNS [yes: boolean]; 

CanYouTakeProcX: type ■ procedure [ 
source: Handle, 
background: boolean false] 
RETURNS [yes: boolean]; 

The source's CanYouTakeProc is invoked to determine if the container source can take the 
current selection, selection is an obsolete parameter that is not used. If the 
CanYouTakeProc returns yes ■ true, then the source's TakeProc may be called. 
CanYouTakeProcX takes a parameter background that asks if the source can take the 
current selection in the background. CanYouTakeProcX is exported by 
ContalnerSourceExtra. Fine point: Supplying a CanYouTakeProcX is optional. However, if the source 
suppiys the CanYouTakeProcX. it muat also still provide a a CanYouTakeProc, even though the implementation of 
one may call the other. 

This routine is intended to provide an efficient check on the compatibility of the objects 
being copied or moved. The common use of this routine is to provide feedback to the user. If 
a CanYouTakeProc returns true, the client may choose to highlight the target. This is 
normally at the level of a file-type check. More elaborate checking is not necessary; for 
example, a Hle-backed container source would not want to check the source for protection 
or uniqueness violations. These should be handled by the TakeProc. 



TakeProc: type « procedure [ 
source: Handle, 

copyOrMove: Sei«ction.CopyOrMove. 
afterHint: Itemlndex <- nullltem, 
withlnSameSource: boolean «- false, 
changeProc: ChangeProc <-nil, 
changeProcOata: long pointer «- nil, 
selection: Seiectton.ConvertProc «-nil] 
RETURNS [ok: boolean]; 

TakeProcX: type « procedure [ 
source: Handle, 

copyOrMove: Seiection.CopyOrMove, 
afterHlnt:ltemindex 4-nullltem, 
withinSameSource: boolean false, 
changeProc: ChangeProc 4-nil, 
changeProcOata: long pointer 4-nil, 
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mgr. Seiectionx. Saved <-s«iectionX.nuli Manager] 
RETURNS [ok: boolean); 

beforeltemZero: Itemlndex ■ ltenrilndex.LAST- 1; 

The source's TakeProc is invoked to add items to the container source. copyOrMove tells 
the source whether to do a move or a copy of the current selection (which can be obtained 
by S«i«ction.Convert). afterHint indicates the item the new item should be inserted after. 
Fine point: This is only a hint to the container source, since the ultimate position of the new item may depend on a 
sort order built in to the source. afterHint defaults to nullltem, which indicates that the caller 
doesn't care where the new item goes. If afterHint ■ beforeitemZero, the source should 
insert the new item before the first item. changeProc must be called if the TakeProc causes 
the source to change. withinSameSource ■ true indicates to the source that the item(s) 
being moved or copied into the source are also in that same source; such as when the user 
moves or copies something from one place in a container to another place in the same 
container. This case usually involves some special case processing by the source (especially 
for move). changeProc and changeProcData are described in more detail in the next 
section, selection is an obsolete parameter that is not used, ok indicates whether the 
TakeProc was successful or not The use of this routine is usually be preceded by a call to 
the source's CanYouTakeProc. 

TakeProcX is the same as TakeProc with the addition of the mgr parameter that indicates 
the source of the items to be copied or moved. If mgr ■ SeiectionX.nulll^gr, the source is the 
current selection. Otherwise, mgr is an encapsulated selection that can be converted with 
Seiectionx.ConvertX. See the Selection chapter for more information on encapsulated 
selections. Finie point: Supplying a TakeProcX is optional. However, if the source supplies the TakeProcX, it 
must also still provide a a TakeProc, even though the implementation of one may call the other. 

If the source supports concurrency, these procedures must support the '^between calls lock" 
convention. See §19.2.5 for more details. 

19.2.4 ChangeProc Types 

A source's ConvertProc, OeleteltemsProc, ItemGenericProc, and TakeProc all take a 
ChangeProc as an input parameter. This ChangeProc must be called by the source 
whenever any item or items in the source changes. This allows the ContainerWindow 
display code to keep the display up to date with the source. For example, a call to the 
source's ItemGenericProc with an atom of Props will cause a property sheet to be displayed 
for an item. If the user then edits, for example, the name of the item, and then closes the 
property sheet, the source must detect this change, update its backing, and call the 
ChangeProc that was passed into the ItemGenericProc. This ChangeProc (supplied by 
ContainerWindow) then causes the changed item(s) to be redisplayed. 

ChangeProc: type » procedure [ 
changeProcData: long pointer, 
changelnfo: Changelnfo ]; 

A ChangeProc and changeProcData are passed to a source's ConvertProc, 
DeieteitemsProc, ItemGenericProc, and TakeProc . Since the cliangeProcData had to be 
allocated from someplace the ciiangeProc must always be called, even if there were no 
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changes to the source. The source must call the ChangeProc with the changeProcOata and 
any changelnfo. 

Changelnfo: type « record [ 

var: select changeType: ChangeType from 
replace ■ > [item: Itemlndex], 

insert » > [insertlnfo: long descriptor for array of Editlnfo], 
delete ■ > [deletelnfo: Editlnfo], 
allt noChanges ■ > nuu, 
endcase]; 

ChangeType: type ■ { replace, insert, delete, all, noChanges}; 

Changelnfo is passed to the ChangeProc to tell the display code exactly what changed. A 
container source can be smart and pass specific Changelnfo (for example, "3 items were 
Inserted after item 4 and 2 items were inserted after item 6*' may be constructed with the 
insert variant), or be dumb and simply pass the all variant, which causes a total repaint of 
the container display, replace indicates that a single item has changed, insert indicates 
that one or more items have been inserted, delete indicates that one or more items have 
been deleted, all indicates that the entire source has been changed. 

Editlnfo: type m record [ 
afterltem: Itemlndex, 
nitems: cardinal]; 

Editlnfo is used with the insert and delete variants of Changelnfo to indicate how many ^"^^ 
items have been inserted or deleted, and where they were inserted at or deleted from. 



19.2.5 Marks 

A container source is defined as a sequence of items from [0.. length). Every time a item is 
inserted or deleted In the source, the rest of the items in the source are effectively 
renumbered. This causes trouble for ContainerWindow. If the user selects the fifth item, 
the container window must be able to continue to tie the selection to the object the user 
pointed at, even if other items have been added or deleted by concurrent operations. 

We define marks to get around this problem. A mark is a handle on a item in the source 
that tracks that item when its item number changes. 

The ContainerCache interface supports marks which can be used to implement 
ContainerSource marks. See the ContainerCache chapter for more information. 

Mark: type « long pointer; 

SetMarkProc: type * procedure [ 
source:Handie, 
index: Itemlndex] 
RETURNS [mark: Mark]; 
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To mark an item, the client calls the SetMarkProc for a source and supplies an index to 
indicate the item to be marked. This creates a new mark. Mark and SetMarkProc are 
defined in ContainerSourceExtra. 

IndexFromMarkProc: type ■ procedure [ 
source: Handle, 
mark: Mark, 

lockSource: boolean 4- false] 
RETURNS [index:itemlndex]; 

IndexFromMarkProc takes a mark created with SetMarkProc or MoveOrCreateMarkProc 
and returns the current item index for mark as index . 

A typical use of marks is to get the value of a mark and then call one of the source procs 
that takes an item index (i.e. StringOfltemProc, ItemGenericProc, ConvertltemProc, 
OeieteltemsProc, SetBusy, and TakeProc/TakeProcX). But with concurrency, the item 
index for a particular mark could change inbetween the time we call IndexFromMarkProc 
and when we call the source procedure. We establish a Ijetween-calls lock" convention to 
address this problem. Calling IndexFromMarkProc with lockSource <- true tells the 
container source to lock itself until client calls back to a procedure that takes an itemlndex 
or until the client unlocks the source with SetBusy (see §19.2.6). Thus the name '^between- 
calls lock": the container source is only locked inbetween the call to IndexFromMarkProc 
and the next proc that takes an itemlndex. The other approach to use would be to lock the 
source, call IndexFromMarkProc, call source proc with the index, and unlock the source. 
This would result in the source being locked for the call to the source proc. This may be a 
undesirable if source proc might take a long time. Using lockSource unlocks the source 
again as soon as the source proc is called. Important point: if IndexFromMarkProc is 
called with locksource « true and a source proc is not called, the client must call SetBusy 
to unlock the source. 

IndexFrommarkProc is defined in ContainerSourceExtra. 

FreeMarkProc: type « procedure [ 
source: Handle, 
mark: Mark]; 

FreeMarkProc frees mark when the client is done with it. FreeMarkProc is defined in 
ContainerSourceExtra. 

MoveOrCreateMarkProc: type « procedure [ 
source:Handle, 
mark: Mark, 
newlndex:ltemlndex] 
RETURNS [newMark: Mark]; 

MoveOrCreateMarkProc is useful for pointing an existing mark at another item newindex. 
If mark is nil, the effect is the same as calling SetMark: a new mark is created. newMark is 
either the old mark updated, or the newly created mark . Even if mark is non-nil, the client 
must reassign mark to newMark because the value of mark may have changed. 
MoveOrCreateMarkProc is defined in ContainerSourceExtra. 
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19.2.6 ContainerSource locking and Busy routines 

If a container source supports concurrency, it must support locking individual items and 
locking the entire container source. ContainerWindow locks individual items (or makes 
them *busy') in response to user operations such as background copy out or background 
drop-on. The container source is responsible for knowing that a particular item is busy and 
responding with a busy status If queried. 

SetBusyProc: type « procedure [ 
source: Handle, 

iteni:itemlndex, - ifltemlndex is nuilltem, refers to whole source, 
newBusyState: boolean] 
RETURNS [succeeded: boolean]; 

IsBusyProc: type « procedure [ 
source: Handle, 

ltem:lteinlndex - ifltemlndex is nullltem, refers to whole source 
1 

returns [busy: boolean]; 

SetBusyProc changes the state of item. If newBusyState is true, item should be made busy, 
if FALSE, item should be made unbusy. IsBusyProc gets the state of item. If the item is busy, 
it returns true. 

If itemindex is nullltem, Set/lsBusyProc refer to the entire source rather than an individual 
item. When the entire source is locked, no items should be added or deleted to the source 
until the source is unlocked again. If the source is already locked when SetBusyProc is 
called, the call should wait until the source is unlocked. 

Important implementation point: Because of the callback design of containers, 
SetBusyProc may be called in a nested fashion to lock a source: i.e., ContainerWindow may 
call SetBusyProc[newBusystate: TRUE] and later make the same call again with call with 
newBusyState: FALSE in the mean time to unlock the source. The container source should 
implement source locking such that nested calls to SetBusyProc from the same process do 
not lock, but a call from a different process will lock. Thus the first call from a given 
process locks the source for that process. §19.4.3 gives one example of how to implement a 
source locking scheme that will support these conventions. Fiira point: if possible, this procedure 
should be relatively cheap. ContainerWindow will call it frequently: it will be called while tracking the selection 
for the user, for example. 

19.2.7 Errors 

A container source may raise Error or Signal as appropriate. 

Error: error [code: ErrorCode, msg: XString.Reader nil, 
error: error nil. errorOata: long pointer to unspeofied 4- nil]; 

Signal: signal [code: ErrorCode, msg: XString.Reader 4- nil. 
error: error nil. errorOata: long pointer to unspeofied ^-nil]; 

A source's ItemfienericProc (and ConvertltemProc and OeleteltemsProc) should never 
assume that it has been called by a ContainerWindow, and therefore should never call 
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such facilities as Attention.Post or UserTerminal.BlinkOisplay. (The application might be 
called by CUSP, for example.) Rather, the source should raise ContainerSource. Error or 
Signal with an appropriate message. The caller of the source's ItemGenericProc should 
catch these errors and do the appropriate thing. In the typical case, the ContainerWindow 
will call the source's ItemGenericProc and catch the error and call Attention.Post with the 
passed message. CUSP could catch the error and log the message in a log file, msg is the 
message to display to the user, error is the actual lower-level error that ocurred that caused 
Error or Signal to be raised. errorOata points to any additional data that accompanied the 
lower level error. 

ErrorCode: type > machine dependent {invalidParameters(O), accessError, fileError, 
noSuchltem, other, last(15)}; 



invaiidParameters 
accessError 

fileError 
noSuchltem 

other 



indicates that some parameters were invalid; for example, the 
source was not the correct type (the Procedures did not match). 

indicates an attempt to perform an operation that violates the 
created access option (for sources that implement access 
controls). 

indicates a file system error (for sources that are backed by files). 

A container source implementation should raise 
Error[noSuchltem] if one of the container source's procedures is 
called with an Itemindex for an item that is not in the source. 

may be raised to indicate any other problem. 



Fine point: Error and Signal are EXPORTed by the FiieContainerSource implementation since ContainerSource has 
no implementation. 



19.2.8 Global change proc 

GetGlobalChangeProcProc: type - procedure [ 
source: ContainerSource.Handie] 

RETURNS [ 

changeProc:ChangeProc, 
data: long pointer, 
window: window.Handle]; 

SetGiobaiChangeProcProc: type • procedure [ 
source: Handle, 
changeProc:ChangeProc, 
data: long pointer, 
window: window.Handle 4-nil]; 

If SetGiobaiChangeProcProc is supplied by the source, container window will call this 
procedure during the Contain«rWindow.Create call to supply a global change proc and data 
that the source can call anytime to update the container window. The container window 
may also give the source the window.Handle for the container window so that clients of the 
source can get at the window if necessary, window may be nil if the client of the source is 
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not ContainerWindow. GetGiobalChangeProcProc allows any client of the source to get 

this information. ^ ^ 

One example of where this is used is in the Busylcon implementation. FileContainerSource 
provides a way for Busylcon to find all the file-backed sources, and once Busylcon finds the 
source a particular file is in, it calls the SetBusyProc to make the file, the calls 
GetGiobalChangeProcProc to get the change proc to allow it to update the container 
window display. 

GetGiobalChangeProcProc and SetGlobalChangeProcProc are defined in 
ContainerSourceExtra. 

19^.9 INLINES 

The following INLINE procedures are provided as a convenience to clients who wish to use 
object notation when calling a container source. ContainerWindow is the main client of 
these procedures. 

ActOn: ActOnProc > inune {...}; 
CanYouTake: CanYouTakeProc « inune {...}; 
ColumnCount: ColumnCountProc « inune {».}; 
Convertltem: ConvertltemProc » inune {...}; 
Deleteltems: DeleteitemsProc > inune {...}; 
GetLength: GetLengthProc « inune {...}; 
ItemGeneric: ItemGenericProc « inune {...}; 
StringOfltem: StringOfltemProc » inune {...}; 
Take: TalceProc > inune {...}; 

19.3 ContainerSource and concurrency 

The ContainerSourceExtra interface defines a number of new container source procedures 
necessary to make concurrent move and copy work in a container source. If a particular 
type of container source does not create a ContainerSourceExtra.Procedures, the container 
window will realize from the absence of these procedures that it cannot support 
concurrency and will not start background operations to or from the source. 

19.4 Usage/Examples 

The reason that Handle is a pointer to a pointer (rather than just a pointer to the 
ProceduresObject) is to allow a container source to save data specific to the source. For 
example, a file-backed source would need to keep a pointer to the file. This is done in the 
following example. 

19.4.1 ContainerSource Example 

1. Declare a ContainerSource.ProceduresObject in the global frame of the module and fill it 
with the appropriate procedures. 

mySourceProcs: ContainerSource.ProceduresObject <— [ ^^ilk^ 
actOn: MyActOn, 
canYouTake: CaniTake, 
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coiumnCount: MyCoiumnCount, 
convertltem: ConvertMyltem, 
deleteitems: OeieteMy Items, 
getLength: GetMy Length, 
itemGeneric: MyltemGeneric, 
stringOfltem: StringOfMyltem, 
take: MyTake]; 

2. Declare a record that has a Contain«rSourc«. Procedures (Procedures, not 
ProceduresObject!) as its Rrst field and initialize this field to point to the 
ProceduresObject declared in the global frame. The rest of the record should contain 
whatever data the source needs in order to perform all the operations it will be 
requested to perform. Also declare a pointer to this record. 

MySource: type » long pointer TO MySourceObject; 

MySourceObject: type « record [ 

procs: Contain«rSource.Procedures @mySourceProcs, 
otherStuff : . . . 1; 

3. When creating the source, allocate the MySourceObject record and fill it with any 
relevant data. Return a pointer to the Procedures field of the record (@ms. procs 
below). Note: This return value is a pointer to a ContaiiMrSourc«.Procedures, which is a 
CofitaimrSourcs.Handle. 

Oeate: pubuc procedure [otherStuff: . . . ] returns [source: contain«rSource.Handle] ■ { 
ms: MySource <— z.new [MySourceObject [otherStuff: otherStuff]]; 
RETURN[@ms.procs]; 

}; 

4. The first thing that every procedure in the ProceduresObject should do is loophole the 
ContaifMrSourca.Handle that was passed in into a pointer (MySource) to the source's data 
record (MySourceObject). After the loophole, the fields of the source's data record can 
be directly accessed, e.g., ms.otherStuff. This all works because the first field in the 
source's data record is a Procedures. Note that the loophole is actually performed in a 
procedure that also checks to be sure that the Procedures field of the passed source 
actually points to this source's procedtires (iP source ^ # @mySourceProcs then). 

ActOnFile: Contain«rSourca.ActOnProc ■ { 
ms: MySource ■ ValidMySource[source]; 

. . . ms.otherStuff. . . 

}; 

VaiidMySource: procedure [source: ContainerSource.Handle] returns [ms: MySource] a { 
IF source « nil then containerSource.Error [invaiidParameters] ; 
IF source 1 # @mySourceProcs THENContainerSourca.Error[invalidParameters]; 

}; 
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19.4.2 Errors and Signals 

For example, this client catches an NSFile.Error and raises ContainM.Error, passing along the 
ERROR and the NSFito.ErrorRecord: 

message: xstring.ReaderBody; 
errorRecord: NSFii«.ErrorRecord; 
signal: -'GENERIC" signals- nil; 
file 4-NSFii«.0penByReference [reference: ... ! 
NSFii«.Error ■ > { 

errorRecord i- error; 

signal L00PHOLE[NSFii«.Error, signal] ; 

GOTO ErrorExit}]; 
- Operate on the file.- 
NSFii«.CIose[fiie]; 

EXITS 

ErrorExit ■ > { 

message xstrmg.FromSTRINGC"NSFiie.Error"L]; 
CofitaifMrSourca.Error [ 

code: fileError, msg: ©message, error: signal, errorOata: ©errorRecord]; 

19.4.3 Source locking for concurrency 

If a source supports background move and copy via the procedures defined in 
ContainerSourceExtra, it must also provide a means of locking the container source. As 
described in §19.2.5 and §19.2.6, this locking must support a number of conventions: 

1. ContainerWindow must be able to lock the entire source by calling SetitemBusyProc . 
This lock prevents any items from being added or deleted in the source except by the 
calling process. 

2. This locking must be reentrant: one process must be able to call by into the same source 
without getting monitor locked. Other processes must be locked out. 

3. We must be able to support the '^between calls" locking convention described in §19.2.5 
under the discussion of IndexFromltemProc. 

This can be a tricky set of constaints to satisfy. Number 2 is particularly tricky because 
conventional Mesa object locking doesn't do what we want: if we call an entry procedure 
from within another entry procedure, we deadlock. Number 1 implies the container source 
must lock itself whenever it modifies the source so that another call to lock the source will 
block until the modification is complete. 

The example we presem is taken from the FileContainerSource implementation. It 
provides a locking scheme that has proved easy to use and satisifies the requirements 
given above. This example shows code from from the implementation that has been 
modified slightly for clarity. 

FSOps.FiieSourceObject: type > machine dependent record [ 

prOCS (0:0. J1 ): ContainerSource.Procedures, 

monitorLock (2:o,.i s): monitorlock, o6/ect lock field for the source implementation ^^^^^ 
— other source specific fields ... 
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lock (21 :0..79): RECORD [ 

process (0:0..i 5): process 4- niu 
entryCount (i :0..i s): cardinal 4-0, 
lockedBetweenCails (2:o..i5): boolean 4- false, 
exiting(3:0..3i): condition] 

]; 

Enter: PUBUCPROC[fs: FS, how: EnterType <- normal] ; 
Exit: PUBLIC PROC [is: FS]; 



EnterType: type « £ 

normal, — just do normal enter 

getBetweenCallsLock, — set betweenCalls boolean 

lockifNotBetweenCalls — if betweenCalls boolean not set, lock; otherwise nothing 

}; 

To implement our locking, we define two procedures: Enter and Exit. We also define a lock 
record as part of the source specific data to support these two procedures. Every procedure 
we would normally make an entry procedure now calls Enter and Exit around the critical 
code. For any particular source fs. Enter allows a process into the monitor if there are no 
other processes running in the monitor. Once a particular process has the monitor, it can 
call Enter as many times as it wants so long as all Enters and Exits are paired. Any other 
process trying to get into the monitor waits until the nmning process has done its last Exit. 

To support the ''between calls" convention, we add a parameter to Enter to give some 
infomation about what our situation is. Most ordinary clients call with how ■ normal, 
which says 'I want to lock the source.' 

Clients that take an itemlndex and must support "between call" locks call Enter with 
how ■ lockifNotBetweenCalls. This says '*lf IndexFromitemProc was just called and the 
client wanted a between calls lock, don't lock the monitor again; otherwise, acquire the 
monitor." The logic here is that at the end of the Itemlndex procedure we call Exit. If we 
were not in the between calls case, the Exit unlocks the Enter at the beginning of the 
procedure. If we were in the between calls case, the Exit unlocks the Enter done in the 
IndexFromitemProc. 

Finally, to set up the between calls state, IndexFromitemProc calls Enter with 
how • getBetweenCallsLock. 

The implementation below give the implementation for Enter and Exit. Much of the logic is 
dedicated to making sure the between calls logic works correctly. Exit includes some 
debugging code to raise a signal if the number of Exits is more than the number of Enters. 
The entire module is an object monitor on the monitorLock field of the source object. 

FileContainerSourcelmpI: monitor locks fs.monitorLock using fs: FSOps.FS « begin 

Enter: public entry proc [fs: FS, how: EnterType normal] ■ 

BEGIN enable UNWIND « > {}; 

me: process ■ Process. GetCurrentQ; 
select fs.iock.process from 
me a > 

"^^r {if '(how ■ lockifNotBetweenCalls AND fs.lock.IockedBetweenCaiis) THEN { 

f s.lock.entryCount ^ f s.lock.entryCount + 1; 
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IF 'fs.lock.lockeciBetweenCails AND how « getBetweenCalisLock then { 
fs.lock.iockedBetweenCalis 4-true; 

}; 

} 

ELSE fs.lock.lockedBetweenCalls 4- false 
return}; 
NIL • > Nuu; 

ENOCASE ■ > { 

waitCount waitCount ♦ 1 ; 

WHILE fs.lock.process # niloo WAiTfs.iock.exiting; enoloop; 
waitCount <- waitCount-1 ; 

}; 

fs.lock.process me; 
f s.lock.entryCount 1 ; 

fs.lock.lockedBetweenCails 4- how ■ getBetweenCalisLock; 
end; 

UnbaiancedFlleContalnerSourceLocks: signal « code; 
Exit: PUBUC entry PROC[fs: FS] ■ 

BEGIN ENABLE UNWIND a > {}; 

me: process « Proc«ss.GetCurrentD; 

iFfs.lock.entryCount ■ 0 then signal UnbalancedFileContainerSourceLocksQ ; 
fs.iock.entryCount 4— f s.lock.entryCount - 1 ; 
iFfs.lock.enti7Count ■ Othen 

{fs.lock.process «-nil; 

NOTIFY fs.iock.exiting}; 

'-must not be BROADCAST; only the next process on the queue should be allowed 

to run 
end; 

ConvertFileltem is an example of a typical procedure that takes an Itemlndex and 
supports the between calls convention. 

ConvertFileltem: contain«rSourc«.ConvertltemProc ■ 
BEGIN 

fs: FS ■ ValidFiieSource[source]; 

Enter[fs, locklf NotBetweenCalls]; - get a lock if we don't have one 

BEGIN enable UNWIND ■ > Exit[fs]; 

IF inLock THEN Exit[fs]; 

- implement Convertltem 
Exittfsj; 
end; — enable 
end; ~ ConvertFileltem 

IndexFromMark also supports the between calls convention. 

IndexFromMark: ContainerSourceExtra.lndexFromMarkProc ■ { 
fs: FS a ValidFileSource[source]; 
IF lockSource then Enter[fs, getBetweenCalisLock]; 
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index if mark # nil then ContainerCache.indexFromMark[mark] 

ELSE ContainerSource.nuilltem; 

- don't unlock: that will be done in callbacks. 

}; 

SetBusy has the dual function of locking individual items (which uses the between calls 
logic) and locking the entire source. 

SetBusy: ContaiiMrSourc«extra.SetBusyProc ■ 

BEGIN 

IP item # Contain«rSour€«.nullltem THEN ( 
Enter[fs, locklf NotBetweenCails]; 

BEGIN ENABLE UNWIND ■ > Exit[fs]; 

- set busy status for item 

Exit(fs,2100]; 

end;— enable 

} 

ELSE " lock source 

IF newBusyState then Enter[fs] ELSE Exit[fs]}; 
end; 
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20.1 Overview 

The ContainerWindow interface supports the creation of ViewPoint-like container 
windows. A container window provides a user interface that operates on a list of objects. 
The objects are displayed in rows. Each container window has one or more columns, with 
ail rows displaying the same number of columns. 

The ContainerWindow implementation maintains the display and manages user-invoked 
actions such as scrolling, selection, notifications, open within, show next/previous, and so 
forth. CoritainerWIndow takes a body window, a ContainerSource, and a specification of 
the columns and makes the window behave like a container. Note: This interface does not 
depend on NSFile: the objects represented by rows in the container do not have to be backed 
by NSFiles. 

20.2 Interface Items 

20.2.1 Create and Destroy a ContainerWindow 

Create: procedure [ 

window: window. Handle, 
source: ContainerSource. Handle, 
columnHeaders: CoiumnHeaders, 
firstltem: ContainerSource.ltemlndex 4-0] 

RETURNS [ reguiarMenultems, topPusheeMenuitems: M«nuOata.Array Handle]; 

CreateX: procedure [ 

window: window. Handle, 
source: ContainerSource. Handle, 
columnHeaders: ColumnHeaders, 
firstltem: ContainerSource.ltemlndex 4-0, 
access: Access 4-fullAccess] 

RETURNS [ regularMenuitems, topPusheeMenuitems: MenuOata.ArrayHandle]; 

CreateXX: procedure [ 
window: window.Handle, 
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source: ContainerSource.Handie, 
SOurceX:Contain«rSourceExtra.ProcedureSr 
col umnHeaders: Column Headers, 
firstltem: ContaimrSourc«.ltemlndex 4-O, 
access:Access 4-fullAccess] 

RETURNS [regularMenultems, topPusheeMenultems: M«nuOata.ArrayHandre]; 
ColumnHeaders: type « long oescrirtor for array of Col umnHeaderlnfo; 
ColumnHeaderlnfo: TYPE - record [ 

width: CARDINAL, 

wrap: boolean. 

heading: xstrifig.ReaderBody]; 

Access: type ■ packed array AccessType of BooleanFalseOefauit; 

BooieanFaiseOefault: TYPE • boolean 4- false; 

AccessType: type ■ {open, dropOn, convert, add, delete, props}; 

fuilAccess: Access « au[true]; 

readOniyAccess: Access ■ [open: true, convert: true, props: true]; 

dividerAccess: Access • [open: true. dropOn: true, convert: true, props: true]; 

Create turns an ordinary window into a container window, window must be a 
StarWindowSheil body window, source supplies a source of items to be displayed and 
manipulated (see the ContainerSource and FileContainerSource interfaces). 

CreateX Is just like Create, but with the additional access parameter. ContainerWindow 
displays an appropriate message to the user if s/he tries to do something for which proper 
access is not provided, open, delete, and props access give the user the capability to open 
icons, delete them, or open a property sheet on them. dropOn allows the user to drop 
something on an item, convert controls whether the ContainerWindow supports 
s«i«ction.Convert (and thus copy and move out), add controls whether the user is allowed to 
add anything to the container display itself. 

CreateX, Access, AccessType, full Access, readOniyAccess, and dividerAccess are defined in 
ContainerWindo wE xtra3 . mesa. 

CreateXX is just like Create and CreateX, but adds the sourceX parameter to provide extra 
container source procedures needed for concurrency. (See the ContainerSource chapter for 
more information on concurrency in containers.) CreateXX is defined in 
Container WindowExtra4. mesa. 

ColumnHeaders describes the column widths and supplies column headings. The columns 
will be displayed in the order given by this array. For each column, width is the number of 
bits the column should take, and heading is a string that will be displayed at the top of the 
column, wrap indicates what to do when a string that the container window wants to 
display is wider than width. If wrap » true , the string should be wrapped around, 

otherwise, it will be truncated. Fine Point: coiumnHeaders is copied by Create, so this structure may be in 
the client's local frame. 
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firstltem indicates the item that should be displayed first when the container window is 
initially displayed. 

regularMenultems and topPusheeMenultems are the menu items that the container 
window needs to have in the StarWindowShell. They should be added (by the client) to the 
menu that is installed in the StarWindowShell which this container window is a part of 
(these contain menu items such as Show Next and Show Previous ). 

Destroy: procedure [window: window. Handle]; 

Destroys the data associated with the container window. Does not destroy the window 
itself. May raise Error [ notAContainerWindow ]. 

20.2.2 Item operations 

The individual containees in a container window are referred to as items (from 
Contain«rSourc«.ltemlndex) They are sequentially numbered starting with zero. 

DeieteAndShowNextPrevious: procedure [ 
window: window.Handle, 
item: contain«rSourc«.ltemlndex, 
direction: Direction next]; 

DeieteAndShowNextPrevious: procedure [ 
window: Window. Handle, 
item: ContainerSourct.ltemlndex, 
direction: Direction next] 
returns [newOpenShell : starWindowSiieii.Handle]; 

Direction: type « {next, previous}; 

DeieteAndShowNextPrevious deletes item from the container source and the display, then 
displays the next or previous item. When this proc is called, the container window shell is 
expected to be on top. In particular, the shell of the item named in the item parameter 
should have been destroyed. So to implement this, if this item is opened within the 
container window, the client should call StarWindowSh«il.Pop until the shell returned from 
that call is equal to the container window shell. The second DeieteAndShowNextPrevious 
is defined in ContainerWindowExtra2.mesa. It is identical to the first one, but 
additionally returns the shell just opened. May raise Error[notAContainerWlndow] or 
Error[noSuchltem] . 

GetOpenitem: procedure [window: window. Handle] 

RETURNS [item: Contain«rSour€e.ltemlndex ^Contain«rS9urc«.nullitem]; 

Returns the item that is currently open within the container. If no item is open, returns 
ContainerSource.nul litem. May raise Error[notAContainerWindow]. 
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GetSelection: procedure [window: window.Handle] 
RETURNS [first, lastPlusOne: ContainerSourceJtemlndex]; 

Returns the items currently selected in the ContainerWindow. first ■ last » 
Contain«rSourc«.nui litem means there is no selection. 

Selectltem: procedure [window: window.Handle, 
item: Contain«rSourc«.ltemlndex]; 

Selects the specified item and implicitly calls Malceltem Visible. IVIalceitemVisible is in a 
friends-level interface. Note: Makeltem Visible Forces item to be visible in window. If there 
is more than a screenful of items left following item, it is put at the top of the window. If 
less than a screenful remains, item is put at the bottom of the window with as many items 
as will fit before it. May raise Error(notAContainerWindow] or Error(noSuchitem]. 

20.2.3 Operations on a ContainerWindow 

isit: PROCEDURE [window: window.Handle] returns [yes: boolean]; 

Returns true if the window passed in is a ContainerWindow. 

GetSource: procedure [window: window.Handle] 
RETURNS [source: ContainerSourcc.Handle]; 

Returns the ContainerSource associated with this window. May raise 
Error[notAContainerWindow]. SetSource allows the client to change the source and the 
SourceModifyProc allows the client to modify the source. 

KeepWindowOpen: procedure [window: window.Handle]; 
WindowCanClose: procedure [window: window.Handle]; 

KeepWindowOpen prevents the use from closing the container window. If the user tries to 
close the window, the message "Can't close that container while background operations are 
going on inside it." is posted. WindowCanClose allows the user to close the window again. 
In BWS 4.3, these procedures in are Contain«rWindowEztra6. 

SetSource: procedure [ 

window: window.Handle, newSource: Contain«rSourc«.Handle] 
RETURNS [oldSource: Handle]; 

SourceModifyProc: type « procedure [ 

window: window.Handle, source: Contain«rSour€«.Handle] 
RETURNS [changelnfo: Changelnfo]; 

ModifySource: procedure [window: window.Handle, proc: SourceModifyProc]; 

ModifySource calls the source modification proc from within its monitor. 

Update: procedure [window: window.Handle]; 

Called when the correspondence between the source and the display is invalid. Items in the 
display will be redisplayed to reflect any changes in the source. May raise 
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Error[nOtAContainerWindOw]. Fine Point: Clients will not normally need to call this routine unless they 
manipulate the source directly. All user-initiated operations on a ContainerWindow cause the display to be 
updated automatically. 

20.2.4 Errors 

Error: error [code: ErrorCode]; 

ErrorCode: type * machine dependent {notAContainerWindow(0), noSuchitem, iast(7)}; 

Any operations that operate on a container window may raise this error. 
notAContainerWindow is raised if the window passed in is not a container window (i.e., 
was not passed to Create). noSuchltem may be raised if an operation specifies a non- 
existent item. 

20.3 Usage/Examples 

The following example is taken from the implementation of the FiieContainerSheil 
interface. It illustrates the steps Involved in creating a container window: creating a 
container source, creating a StarWindowShell, creating a body window inside the shell, 
creating the container window, and finally merging the menu items returned by 
ContaifMfWindow.Create with its own menu commands and installing those commands in the 
shell. It also gives a sample StarWindowShell transition procedure that will destroy the 
container source and the container window. 

- From FileContainerSheiilmpl.mesa 

MenultemSeq: type « record [ 

SEQUENCE length: cardinal op ivi«nuOata.ltemHandle]; 

Create: public procedure [ 
file: NSFU«.Reference, 

columnHeaders: Contaimrwindow.ColumnHeaders, 

columnContents: FiicContaiirarSoum.CoiumnContents, 

regularMenultems, topPusheeMenultems: MenuOata.ArrayHandie nil, 

scope: NSFiie.Scope 0* 

position : ContainerSourcaJtemlndex 4- 0, 

options: FilflContain«rSourc«.Options 4- []] 

RETURNS [shell: StarVVindowShell.l4andie] ■ 

BEGIN 

body: window.Handie 4- nil; 
source: ContainerSource.Handle 4->nil; 

cwRegularMenuitems, cwTopPusheeMenultems: M«nuData.ArrayHandle; 

mergedMenultems: long pointer to MenultemSeq <~ nil; 

menu: MenuOata.MenuHandle; 

name: xstring.ReaderBody; 

ticket: Containee.Ticket; 

data: containee.Data 4-[file]; 

type: NSFiie.Type; 

smaliPicture: xstring.Character; 
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IF file • NSFito.nullReference then return [ [nil] ]; 
source <~ FileContainerSource.Create [ 

file: file, 

columns: coiumnContentSr 
scope: scope, 
options: options]; 

[name, ticket] 4->cofrtainM.GetCachedName [@data]; 

type 4- CoiitainM.GetCachedType[@data]; 

smailPicture 4- containM.Getlmpiementation[type].smallPicture; 

shell 4- starWindowSh«ii.Create [ 
name: @name, 
namePicture: smailPicture, 
sleeps: false, 

transitionProc: DestroyProc]; 

ContainM.ReturnTicket [ticket] ; 

body <-starvvindowSh«ii.CreateBody [sws: shell, box: [[0,0],[700, 29999]]]; 

[cwRegularMenuitems,cwTopPusheeMenultems] 4-contaimrWindow.Create [ 
window: body, 
source: source, 

columnHeaders: columnHeaders, 
firstltem: position]; 

mergedMenultems *- MergeMenuArrays [cwRegularMenultems, regularMenuitems]; 
IF mergedMenultems # nil then 

BEGIN 

menu 4~ MenuOata.CreateMenu [ 

zone: starWindowSh«ii.GetZone[shell], 
title: NIL, 

array: OESCRiPTOR[mergedMenultems], 

copyltemslntoMenusZone: true ]; 
StarWindowSh«ii.SetRegularCommands [shell, menu]; 
z.FREE[@mergedMenuitems]; 
end; 

mergedMenultems *~ MergeMenuArrays [cwTopPusheeMenultems, 

topPusheeMenuitems]; 

menu ^ MenuOata.CreateMenu [ 

zone: starWindowSheii.GetZone[shell], 

title: NIL, 

array: OESCRiPTOR[mergedMenultems], 

copyltemslntoMenusZone: false ]; 
starwindowSheii.SetTopPusheeCommands [shell, menu]; 
return [shell]; 
end; 
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DestroyProc: StarWindowShell.TransitionProc ■ 
< <[sws: StarWindowShell.Handie, state: StarWmdowSheii.State]> > 
BEGIN 

IP state « dead then { 

cw: window.Handle GetContainerWindow[sws]; 

source: Contain«rSouK«.Handle GetContainerSource(sws]; 

Contain«rSourc«.ActOn [source, destroy]; 

Contain«rWindow.Destroy[cw]; }; 
return; 
end; 

MergeMenuArrays: proc [itemArrayl, itemArray2: M«nuOata.ArrayHandle] 
RETURNS [mergedSeq: long pointer to MenultemSeq] ■ 

BEGIN 

i: CARDINAL 4-0; 

iFitemArrayl ■ NiLANDitemArray2 « nil then return{nil]; 

mergedSeq <-z.NEW[MenultemSeq(itemArray1. LENGTH itemArray2.LENGTH]]; 

FOR j: cardinal in [0..itemArray1 .length) do 

mergedSeqCn <-itemArray1[j]; 

I <- i ♦ 1 ; 

ENDLOOP; 

FOR j : CARDINAL IN [0..itemArray2.LENGTH) do 
mergedSeq[i] 4- item Array 2(j]; 
1 4-i ♦ 1; 

ENDLOOP; 

RETURN[mergedSeq]; 
end; 
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21.1 Overview 

In performing various functions, an application may wish to save and retrieve state from 
one notification to the next. This is an immediate consequence of the notification scheme, 
for a tool cannot keep its state in the program counter without stealing the processor after 
responding to an event. Thus the application must explicitly store its state in data. Because 
most notification calls to the application provide a window handle, it is natural to associate 
these contexts with windows. The context mechanism provides an alternative to the 
application's having to build its own associative memory to retrieve its context, given a 
window handle. 

Typically, an application obtains a unique Type for its context data by calling UniqueType 
in the startup code for the application. Whenever a window is created, the client allocates 
some context data and calls Create to associate that data with the window. Whenever the 
client is called to perform some operation on the window (for example, to display the 
contents of the window or to handle a notification), it calls Find to retrieve the data saved 
with the window. Finally, when the window is being destroyed, the client (orViewPoint) 
calls Destroy, which calls the client's OestroyProcType to give the client an opportunity to 
free the data. 

21.2 Interface Items 

21.2.1 Creating/Destroying a Context 

UniqueType: procedure returns [type: Type]; 

The procedure UniqueType is called if a client needs a unique Type not already in use 
either by ViewPoint or by another client. If no more unique types are available, the error 
Error[tooiy/lanyTypes] is raised. 

Create: procedure [ 

type: Type, data: Data, proc: DestroyProcType, window: Window.Handle]; 
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The procedure Create creates a new context of type type that contains data. The context is ^fn^ 
associated with window; it is said to "hang** on the window. If window already has a 
context of the specified type, it raises the error Error[duplicateType]o If the window is nil, 
it raises the error Error[windowisNIL]. The proc is supplied so that when the window is 
destroyed, all of the context can be destroyed (deallocated). 

Type: type - machine dependent{ 
ali(0Kfirst(1)« lastAllocated(37737B), last(37777B)}; 

Type is unique for each client of the context mechanism. An argument of this type is passed 
to most of the procedures in this interface so that the correct client data can be identified. 

Data: type * long pointer to unspeopieo; 

Data is the value that a client may associate with each window. It is typically a pointer to a 
record containing the client's state for some window. 

DestroyProcType: type » procedure [Data, Window.Handle]; 

A DestroyProcType is passed to Create so that the client can be notified when the context 
should be destroyed. This may be the result of the window being destroyed. 

Destroy: procedure [type: Type, window: Window.Handle]; 



The procedure Destroy destroys a context of a specific type on window. If the context 
exists on the window, it calls the DestroyProcType for the context being destroyed. 

DestroyAII: procedure [window: Window.Handle]; 

The procedure DestroyAII destroys all the contexts on window. Fine point: Destroy AU can be 
very dangeroua because ViewPoint keeps its window-specific data in contexts on the window. Destroy All should 
not be used except in special circumstances. It is called by the routines that destroy windows. 

NopDestroyProc: DestroyProcType; 

The procedure NopDestroyProc does nothing. It is provided as a convenience to clients that 
do not want to create their own do-nothing DestroyProcType to pass to Create. 

SimpieDestroyProc: DestroyProcType; 

The procedure SimpieDestroyProc merely calls the system heap deallocator on the data 
field. It is provided for clients whose context data is a simple heap node in the system zone. 

21.2.2 Finding a Context on a Window 

Find: procedure [type: Type, window: Window.Handle] returns [Data]; 

The procedure Find retrieves the data field from the specified context for window, nil is 
returned if no such context exists on the window. 
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FindOrCreate: procedure [ 

type: Type, window: Window.Handle, createProc: CreateProcType] returns [Data]; 

The procedure FindOrCreate resolves the race that exists when creating new contexts in a 
multi-process environment. If a context of type type exists on window, it returns the 
context's data; otherwise, it creates a context of type by calling createProc and then 
returns data. If the window is nil, it raises the error ErrorfwindowlsNIL]. 

CreateProcType: type ■ procedure returns iData, OestroyProcType]; 

CreateProcType is used by FindOrCreate. The procedure passed in as an argument to 
FindOrCreate is called to create a context only if a context of the appropriate type cannot be 
found. 

Set: procedure [type: Type, data: Data, window: Window.Handle]; 

The procedure Set changes the actual data pointer of a context. Subsequent Finds will 
return the new data. Note: The client can change the data that the data field of a context 
points to at any time. This could lead to race conditions if multiple processes are doing 
Finds for the same context and modifying the data. It is the client's responsibility to 
MONITOR the data in such cases. If the window is nil, it raises the ERROR Error[windowisNiL]. 

21.2.3 Acquiring/Releasing the Context 

Acquire: procedure [type: Type, window: Window.Handle] returns [Data]; 

The procedure Acquire retrieves the data field from the specified window. It returns nil if 
no such context exists on the window. It also locks the context object so that no other calls 
on Acquire or Destroy with the same type and window will complete until the context is 
freed by a call on Release. 

Release: procedure [type: Type, window: Window.Handle]; 

The procedure Release releases the lock on the specified context object for window that 
was locked by the call on Acquire. If the specified context cannot be found or if it is not 
locked. Release is a no-op. 

21.2.4 Errors 

ErrorCode: type ■ {duplicateType, windowlsNIL, tooManyTypes, other}; 

duplicateType is raised by Create if a context of the given type already exists on the 
window passed as an argument. 

windowlsNIL is raised if the client has passed in a nil window. 

tooManyTypes is raised if UniqueType has been called too many times. 

Error: error [code: ErrorCode]; 

Error is the only error raised by any of the Context procedures. 



21-3 



21 



Context 



21.3 Usage/Examples 

Acquire and Release can be used in much the same way as a Mesa monitor (See the Mesa 
Language Manual: 610E00150). It is important that the client call Release for every 
context that has been obtained by Acquire; this is not done automatically. The cost of doing 
an Acquire is barely more than entering a monitor and doing a Find. Using this technique 
allows the client to monitor its data rather than its code. 

If several tools must share global data, it is possible to place a context on 
windovtf.rootWindow that is never destroyed, even when the bitmap is turned oft To share 
a Type without having to export a variable, use one in the range (lastAllocated.Jast]. 
Contact the support org^anization to have one allocated to you. 

21.3.1 Example 

myContextType: Cont«xt.Type 4-Context.UniqueTypeQ; 

MyContext: type « long pointer to MyContextObject; 

MyContextObject: type > record [...]; 

sysZ: uncounted ZONE 4- H«ap.systemZone; 

MakeShellAndBodyWindow: procedure ■ { 

myContext: MyContext sysZ.NEW [MyContextObject [ 

— initialize fields of MyContextObject — 1 ]; 

— Note: If some field of MyContextObject were a pointer to some more allocated 
storage, then the Cont«xt.SimpieOestroyProc would not be used. A dient'Supplied 
DestroyProcType that freed both MyContextObject and the storage pointed to by 
MyContextObject would have to be provided, 

shell: starwindowSh«ii.Create [...]; 

body: starwindowSiwii.CreateBody [sws: shell, 

repaintProc: MyRepaint, 

bodyNotifyProc: MyNotify]; 
Cont«xt.Create [type: myContextType, 

data: myContext, 

proc: Cont«xt.SimpieDestroyProc, 

window: body]; 
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MyRepaint: PROCEDURE [window: window.Handle] ■ { 
myContext: MyContext FindContext [window]; 

}i 

MyNotify: TiP.NotifyProc ■ { 

myContext: MyContext *- FindContext [window]; 

}; 

FindContext: procedure [window: window.Handle] 
RETURNS [myContext: MyContext] ■ { 
myContext ^cont«xt.Find [myContextType, window]; 
IF myContext • nil then error; 

}; 
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21.4 Index of Interface Items 



Item Page 

Acquire: procedure 3 

Create: procedure 1 

CreateProcType: TYPE 3 

Data: type 2 

Destroy: procedure 2 

DestroyAII: procedure 2 

DestroyProcType: type 2 
Error: error ^ 3 

ErrorCode: TYPE 3 

Find: procedure 2 

FindOrCreate: procedure 3 

NopOestroyProc: procedure 2 

Release: procedure 3 

Set: PROCEDURE 3 

SimpieOestroyProc: procedure 2 

Type: type 2 

UniqueType: procedure 1 




21-6 



Cursor 



22.1 Overview 

The Cursor interface provides a procedural interface to the hardware mechanism that 
implements the cursor on the screen. This interface defines several cursor shapes as well as 
operations for client-defined cursors. Because there is a single global cursor, it should be 
mAnipulated only through this interface and only from the notifier process. 

The major data structure defined in this interface is the Object, which defines not only the 
array of bits that represents the picture of the cursor but also its hot spot. The hot spot of a 
cursor consists of the coordinates within the 16-by-16 array that indicate the screen 
position pointed to by the mouse. The hardware position of the cursor is always in the 
upper-left comer of the bit array. For many cursor shapes, this position is not where the 
cursor points. For example, the pointRight cursor shape is a right-pointing arrow whose 
hot spot is at the tip of the arrow. 

There can be up to 256 different cursors, limited by the size of the Type enumeration. The 
first several types are system-defined. Clients may call UniqueType to allocate an unused 
type for their own use. 

This interface is typically used to change the cursor either by calling Set to set it to one of 
the system-defined cursors or by calling Store. To restore the cursor, save it into an Object 
by calling Fetch before it is changed. 

22.2 Interface Items 

22.2.1 Ms^or Data Structures 

Handle: type * long pointer to Object: 

Object: TYPE * RECORD [info: Info, array: userTerminaLCursorArray]: 
Info: TYPE « RECORD [type: Type, hotX: [0..16), hotY: [0..16)]; 



22-1 



Cursor 



Type: TYPE a MACHINE OEPENOENT{ 

biank(O), bullseye(1), confirm(2), ftpBoxes(3), hourGlass(4), lib(5), menu(6), 
mouseRed(7), pointOown(8), pointLeftO), pointRight(10), pointUp(11), 
questionMark(12), scroilOown(13), scrollLeft(14), scrollLeftRight(15), scroliRight(16), 
scrollUp(17), scroUUpOown(18), textPointer(19)» groundedText(20), move(21 ), 
copy(22), sameAs(23), adjust(24h row(25), coiumn(26K last(377B)}; 

Object defines the type and hot spot of the cursor as well as the 16-by°16 array of bits that 
represent the cursor's picture. 

Info contains the type and the hot spot of a cursor. 

Defined: type > Type[biank..coiumn]:. 

Defined is the subrange of Type that contains the system-defined cursors. 

22.2.2 Setting the Cursor Picture 

Set: PROCEDURE (type: Defined]; 

Set sets the displayed cursor to be one of the system-defined cursors. 
Store: procedure [h: Handle]; 

Store sets the displayed cursor to the cursor described by h. 



StoreCharacter: procedure [c: xchar.Character]; 

StoreCharacter stores the system font picture of character c into the cursor. The info is set 
to [type: coiumn.succ, hotX: 8, hotY: 8]. 

StoreNumber: procedure [n: cardinal]; 

StoreNumber sets the cursor picture to be the nimiber n moo 100. If n is less than 10, the 
single digit is centered in the cursor. The info is set to [type: coiumn.succ.succ, hotX: 8, 
hotV: 8]. 

22*2.3 Getting Cursor Information 
Fetch: procedure [h: Handle]; 

Fetch copies the current cursor object into the object pointed to by h. 
Getlnfo: procedure returns [info: Info]; 
Getlnfo returns the hot spot and type of the current cursor. 
FetchFromType: procedure [h: Handle, type: Defined]; 

FetchFromType copies the system-defined cursor object corresponding to type into the 
object pointed to by h. 
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22.2.4 Miscellaneous Operations 

MovelntoWindow: procedure [ 
window: window.Handle, place: window.Place]; 

MovelntoWindow moves the cursor to the window-relative place in window. 

Swap: PROCEDURE [old, new: Handle]; 

Swap places the displayed cursor object in old f and Stores the new. It is equivalent to 
FetchCoid]; Store[new]. 

22.2.5 Client-Defined Cursors 

UniqueType: procedure returns [Type]; 

UniqueType lets clients assign a unique type to their defined cursors. It returns a Type 
that is different from all predefined types and from any that have previously been returned 
by UniqueType. The value is only valid during the current boot session. 

22.2.6 Cursor Picture Manipulation 

Invert: procedure returns [boolean]; 

Invert inverts each bit of the cursor picture and inverts the positive/negative state of the 
picture. It returns true if the new state of the cursor is positive. 

MakeNegative: procedure; 

MakeNegative is equivalent to MakePositive followed by Invert. It sets the 
positive/negative state of the cursor to negative. 

MakePositive: procedure; 

MakePositive sets the positive/negative state of the cursor to positive. The state is set to 
positive whenever Set or Store is invoked. 

22.3 Usage/Examples 

The following example shows a client setting the cursor to an hourglass while performing 
some time-consuming action. It first saves the current cursor and restores it when it is 
done, if the action did not change the cursor. If the client knew what the cursor should be, 
the cursor would not have to l>e saved but could be unconditionally set . 

savedCursor: Cursor.Object; 

Cursor.Fetch[@savedCursor] ; 

Cursor.Set(hourGiass] 

— Do action -- 

IF Cursor.GetInf o[].type a hourGlass THENCursor.Store[@savedCursor]; 
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StoreCharacter is t3rpically used to put small pictures in the cursor by using characters 
obtained from simptoT«xtFont.AddClientOef inedCharacter. 
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22.4 Interface Item Index 



Item Page 

Defined: type 2 

Fetch: ptiocEDURe 2 

FetchFromType: procedure 2 

Getlnfo: procedure 2 

Handle: type * 1 

Info: TYPE 1 

Invert: procedure 3 

MoveintoWindow: procedure 3 

MakeNegative: procedure 3 

MakePositive: procedure 3 

Object: type 1 

Set: PROCEDURE 2 

Store: procedure 2 

StoreCharacter: procedure 2 

StoreNumber: procedure 2 

Swap: PRoaouRE 3 

Type: type 2 

UniqueType: PROCEDURE 3 
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23.1 Overview 

Directory allows for clients to add dividers to the directory icon. Directory maintains a 
directory divider containing three top-level dividers: the workstation divider, containing 
those objects that esdst on a per-workstation basis; the user divider, containing those 
objects that exist on a per-user or per-desktop basis; and the network divider, containing 
those objects that exist in the internet (See the Divider and QIDivider interfaces for more 
information about dividers.) 

23.1.1 Predefined Divider Structure 

Directory automatically creates a top-level divider that backs the directory icon. To this 
divider it adds the workstation divider, the user divider, and the network divider. It adds 
three entries to the workstation divider: the prototype folder, the ofiice aids divider, and 
the local devices divider. The user divider is emptied at each logout. Clients of the user 
divider should add their entries at 'each logon. Directory also automatically adds the 
organization- divider to the network divider and the domain divider to the organization 
divider. Clients can add entries to the domain divider (see Figure 23.1). (See the Prototype 
interface for details of how to add prototype icons to the prototype folder and the Divider 
interface for details of how to add entries to the office aids, local devices, and user dividers.) 

23.2 Interface Items 

23.2.1 Adding Items to a Predefined Divider 

DividerType: type ■ {top, ws, user, domain, localDevices, officeAids}; 

A parameter of type DividerType is passed to Add Divider Entry to specify one of the 
predefined dividers. A value of top specifies adding a new top-level divider. 

AddDividerEntry: procedure [ 
divider: DividerType, 
type: NSFii«.Type, 
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label: xstring.Reacier, 
data: long pointer niu 
convertProc: Dividcr.ConvertProc 4- nil, 
genericProc: oividw.GenericProc 4-NiL]; 

AddDividerEntry adds an entry to the divider specified by divider. If divider is equal to top, 
a new top-level divider is added, type specifies the NSFito.Type of the entry. It is used to 
obtain the contaiiM«.impiementation for the entry, label is used to label the entry when it 
appears in the divider's container window. The xstring.Reader bytes are copied, data Is an 
optional data pointer to be supplied in subsequent calls to the GenerlcProc and the 
ConvertProc convertProc is a Divid«r.ConvertProc for the entry, and genericProc is a 
Dhrkiw.GenericProc for the entry. (See the Divider interface for details.) Fine point: The 
predefined dividers are actually implemented by using the Ohrider intez&ce. AddDividerEntry is actually the 
same as oi«id«r J^ddEntry, with the handle arguement replaced by a iMrwfary.OhriderTyp«. 

23^ GetDividerHandle 

GetDividerHandle: procedure [divider: DividerType] returns [handle: oivider.Handte]; 

GetDividerHandle returns the Dhiid«r.handle for the predefined divider specified by divider. 
Clients can use this handle to manipulate the predefined divider with the Divider 
interface. (See the Divider chapter for more information.) 

23.3 Usage/Examples 

See the Divider and CH Divider interfaces for examples of how to add entries to the 
directory. The Divider interface also shows the implementation of AddDividerEntry. 
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Figure 23.1 Predefined Divider Structure 
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23.4 Index of Interface Items 

Item Page 

AddOividerEntry: procedure 1 

GetOividerHandle: procedure 2 

DividerType: type 1 
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24.1 Overview 

The Display interface provides elementary routines for painting into windows on the 
display screen. Procedures are provided for painting points; lines; bitmaps; repeating 
patterns; boxes filled with black, gray, white, or small patterns; circles; circular arcs; 
ellipses; conies; as well as for painting a brush as it moves along an arbitrary trajectory. 
Another procedure allows shifting the current content of a window. Procedures for painting 
text are available in the SimpleTextOisplay interface. 

J The Window interface supplies facilities for managing windows. The introduction section 

of the Window chapter describes the window coordinate system and the process of painting 
into a window. The reader should be familiar with that material. 

As described in the Window chapter, the display background color, which is represented by 
a pixel value of zero, is commonly called white, and a value of one, called black. Note 
however, that the display hardware can also render the picture using zero for black and one 
for white. Clearing or erasing an area of the screen means setting all of its pixels to zero, or 
white. 

The Display interface currently contains procedures that apply to text-namely Block, 
MeasureBiock, ResolveBlock, Character, Text, and Textlnline. They are not supported. The 
SimpieTextDisplay interface provides text painting operations. 

As described in the Window chapter, the standard way for a client to paint into its window 
is to update its data structures, invalidate the portion of its window that needs to be 
painted, and then call a window. Validate routine. Window responds by calling back into the 
client's display procedure to do the painting. Nonstandard ways of painting are discussed 
in the Usage/Examples section of this chapter. 

24.2 Interface Items 

24.2.1 Painting Filled Boxes, Horizontal Lines, and Vertical Lines 
Handle: type » window.Handle; 
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Black: procedure [window: window.Handle, box: window.Box]; 
Invert: procedure [window: window.Handle, box: window.Box]; 
White: procedure [window: window.Handie, box: window.Box]; 

Black and White paint black and white boxes. Invert changes all black pixels to white and 
all white pixels to black in the box. These procedures perform their operation on the 
specified box in window. Horizontal and vertical black lines can be painted by using Black 
with a box that is one pixel wide or tall. 

Olspiay.Handle is provided for backward compatibility. 

24^.2 Painting Bitmaps and Gray Bricks 

The procedures in this section allow the client to paint bitmaps and gray bricks into a 
window. Bitmaps and gray bricks are described in the Mesa Processor Principles of 
Operation. 

The first items below define some convenience types and constants that are used with 
bitmaps and painting. 

BitAddress: type • Envtronffl«nt.BitAddress; 

DstFunc: type ■ BitBit.DstFunc; 

BitBltFlags: type ■ BitBit.BitBltFlags; 

A BitBlt. BitBltFlags is an argument of the Bitmap and Trajectory operations. These flags 
control how source pixels and existing display pixels are combined to produce the final 
display pixels. The Hag constants deHned below cover most of the common cases. 
BitBit. BitBltFlags are described in detail in the Mesa Processor Principles of Operation. 

replaceFlags: BitBltFlags ■ [ 

direction: forward, disjoint: true, disjointltems: true, gray: false, 
srcFunc: null, dstFunc: null, reserved: 0]; 

replaceFlags paints opaque black and opaque white from a bitmap. Source pixels from the 
bitmap overwrite the previous display pixels. 

textFlags, paintFiags: BitBltFlags ■ [ 

direction: forward, disjoint: true, disjointltems: false, gray: false, 
srcFunc: null, dstFunc: or, reserved: 0]; 

textFlags and its synonym paintFiags paint opaque black and transparent white from a 
bitmap source. Black source pixels cause black display pixels. White source pixels leave 
display pixels unchanged. 

xorFlags: BitBltFlags ■ [ 

direction: forward, disjoint: true, disjointltems: false, gray: false, 
srcFunc: null, dstFunc: xor, reserved: 0]; 
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xorFiags is used with a source bitmap to selectively video invert existing display pixels. 
Video inverting is the process of changing white to black and black to white. Black source 
pixels invert the existing display pixels. White source pixels leave display pixels 
unchanged. 



paintGrayFlags, bitFlags: BitBltFtags ■ [ 

direction: forward, disjoint: true, disjointltems: true, gray: true, 
srcFunc: nuii, dstFunc: or, reserved: 0]; 

paintGray Flags paints opaque black and transparent white from a gray brick source. Black 
source pixels cause black display pixels. White source pixels leave display pixels 
unchanged. 

repiaceGrayFiags, isbxFlags: BitBltFiags ■ [ 

direction: forward, disjoint: true, disjointltems: true, gray: true, 
srcFunc: nuil, dstFunc: null, reserved: 0]; 

repiaceGrayFiags paints opaque black and opaque white from a gray brick source. Source 
pixels overwrite the previous display pixels. 

xorGrayFlags, xorBoxFiags: BitBltFiags ■ [ 

direction: forward, disjoint: true, disjointltems: true, gray: true, 
srcFunc: null, dstFunc: xor, reserved: 0|; 

xorGrayFfags is used with a source gray brick to selectively video invert existing display 
pixels. Black source pixels invert the existing display pixels. White source pixels leave 
display pixels unchanged. 

eraseFlags: BitBltFiags > [ 

direction: forward, disjoint: FALSE, disjointltems: FALSE, gray: FALSE, 
srcFunc: complement, dstFunc: and, reserved: 0]; 

eraseFlags erases objects. Previous display pixels are overwritten. 

Bitmap: procedure [ 

window: window.Handle, box: window.Box, address: Environin«nt.BitAddress, 
bitmapBitWidth: cardinal, flags: BHBit.BitBltFlags paintFlags]; 

Bitmap paints the bitmap described by address and bitmapBitWidth into box in window, 
using flags to control the interaction with pixels already being displayed. Bitmap may be 
used to display a gray pattern that is not aligned relative to the window origin, box.dims.w 
must be less than or equal to bitmapBitWidth; this is not checked, f lags.gray is ignored. 

BitAddressFromPlace: procedure [ 

base: Environm«nt.BitAddress, X, y: natural, raster: cardinal] 

RETURNS [Environin«nt.BitAddress]; 

BitAddressFromPlace returns the Environment.BitAddress of the pixel at coordinates x and y 
in the bitmap described by base, raster is the number of pixels per line in the bitmap. This 
procedure is useful for calculating the address parameter of Bitmap. 
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Brick: type * long descriptor for array of cardinal; 

Bricks are used by Gray and Trajectory to describe a repeating pattern to fill an area. The 
maximum size of a Brick is 16 words; each word is one row of the pattern. 

fiftyPercent: Brick; 

f iftyPercent is a brick containing a 50% gray pattern. 
Gray: procedure [ 

window: window.Handle, box: window.Box, gray: Brick 4- f iftyPercent, 
dstFunc: BitBit.DstFunc <~ null]; 

Gray uses the source gray brick to completely fill box in window. If the content of the brick 
to be displayed is not aligned with the window origin, use Bitmap instead. The table below 
describes the effect of dstFunc. 

dstFunc resulting display pixels 

null Source pixels overwrite display pixels. 

or Black source pixels cause black display pixels. White source pixels leave 

display pixels unchanged. 

xor Black source pixels cause the existing display pixels to be inverted. White 
source pixels leave display pixels unchanged. 

and Black source pixels cause black display pixels wherever the display pixels are 
already black. All other display pixels will be made white. 

24.2.3 Painting Points, Slanted Lines, and Curved Lines 

The procedures below paint points, oblique straight lines, and circular arcs and conies. 

Point: PROCEDURE [window: window.Handle, point: window.Place]; 

Point makes the single pixel at point in window black. 

LineStyle: TYPE ■ long pointer to LineStyieObject; 

LineStyieObject: TYPE ■ record [ 
widths: array [O..DashCnt) of cardinal, 
thickness: cardinal]; 

DashCnt: cardinal ■ 6; 

LineStyle describes the style of lines for the Line, Circle, Ellipse, Arc, and Conic operations, 
thickness defines the width of the line in pixels, widths defines the dash structure. Each 
pair of elements is the number of pixels of black followed by the number of pixels of white. 
For example [widths: [4,2,0,0,0,0], thickness: 2] defines the style for a dashed line two 
pixels thick, where the dashes are four pixels on and two off. 
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Line: procedure [ 

window: window.Handle, start, stop: wtndow.Place. lineStyie: LineStyle <-nil, 
bounds: window.BoxHandle <-nil]; 

Line paints a line from start to stop in window. If bounds # nil, the line is clipped to the 
box bounds. If iineStyle is defaulted, the line is solid and is a single pixel wide. 

Grcle: procedure [ 

window: window.Handle, place: windo«v.Flace, radius: integer, 
lineStyie: LineStyle *-Hii, bounds: window.BoxHandle <-NiL]; 

Circle paints a circle centered at place in window, with the given radius. If bounds # nil, 
the circle is clipped to the box taounds. If lineStyie is defaulted, the circle is solid and is a 
single pixel wide. 

Ellipse: procedure [ 

window: window.Handle, center: window.Place, xRadius, yRadius: integer, 
lineStyie: LineStyle ^-nil, bounds: window.BoxHandle 4-nil]; 

Ellipse paints an ellipse with axes centered at center with an x radius of xRadius and a y 
radius of yRadius in window. The axes of the ellipse are parallel to the x-y coordinate 
system. Ellipses with oblique axes may be displayed by using Conic. If bounds # nil, the 
ellipse is clipped to the box bounds. If lineStyie is defaulted, the ellipse is solid and is a 
single pixel wide. 

Arc: PROCEDURE [ 

window: window.Handle, place: window.Piace, radius: integer, 
startSector, stopSector: cardinal, start, stop: window.Place, 
lineStyie: LineStyle 4-nil, bounds: window.BoxHandle 4>-nil]; 

Arc paints a portion of a circular arc centered at place in window, with the given radius. 
The arc goes from the angle detined by start in the startSector to stop in the stopSector. 
Sectors are simply octants numbered from 1 to 8, with northeast being 1 and increasing 
clockwise. If bounds # nil, the arc is clipped to the box bounds. If lineStyie is defaulted, the 
arc is solid and is a single pixel wide. 

Conic: procedure [ 

window: window.Handle, a, b, c, d, e, errorTerm: long integer, 
start, stop, errorRef : window.Place, 

sharpCornered, unboundedStart, unboundedStop: boolean, 
lineStyie: LineStyle 4-NiL, bounds: window.BoxHandle <- nil]; 

Conicpaintstheportionof the curve of the equation ax2 + by2 + cxy +dx + ey + /" = 0 in 
window from start to stop. Instead of passing in the last coeiHcient this procedure takes 
the errorTerm resulting from substituting start into the equation. If the conic contains 
points whose radius of curvature is less than or equal to two pixels, it must be displayed by 
using multiple calls with sharpCornered set to true; otherwise .sharpCornered should be 
false. These "sharp-cornered" conies must be broken up into segments where the corners 
become a new segment's start and stop points. For example, a very long skinny ellipse must 
be displayed in two pieces. errorRef, unboundedStart, and unboundedStop are 
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Ignored. If bounds # nil, the conic is clipped to the box bounds. If iineStyie is defaulted, the 
conic is solid and is a single pixel wide. 

24.2.4 Painting Parailelograms and Trapezoids 

These types and procedures are used to paint parallelograms and trapezoids: 
FixdPtNum: TYPE ■ machini dependent record [ 

SELECT OVERLAID * FROM 

whoieThing ■>[!!: longintegerL 
parts ■ > [frac: cardinal, int: integer], 
endcase]; 

A FixdPtNum is a fixed-point integer with 16 bits of fraction and 16 bits of integer part. 
These numbers can be added and subtracted in a straightforward manner, while division 
and multiplication are more difficult. By using the overlaid record, the fraction and integer 
part may be obtained without shifting or dividing. FixdPtNum can express all practical 
slopes with only small errors. 

Interpolator: TYPE ■ record [ 
val.dVal: FixdPtNum]; 

interpolator is used to define parallelograms and trapezoids. The dVal term is the 
derivative with respect to y, for example, x.dVal is dx/dy. 

BlackParaiielogram: proc[ 

window: l^andie, p: Parallelogram, dstFunc: OstFunc <— null]; 

Parallelogram: TYPE ■ record [ 

x: Interpolator, y: integer, - upper left 
w: natural, — across top, must be positive 
h: natural]; 

BlacicParalleiogram paints the parallelogram defined by p in window. dstFunc acts as in 
the procedure Gray. The parallelogram is defined as below with the slope of the 
parallelogram being p.x.dVal. In Figure 24.1 the slope is two Hfths. BlackParaiielogram 



(p.x.val, p.y) 




Figure 24. 1 Paraiieiogram definition 



optimizes a common case (such as diagonal lines) and runs about twice as fast as 
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GrayTrapezoid by avoiding the second interpolation, the noninteger width, and the gray 
alignment calulations: 

GrayTrapezoid: proc [ 

window: Handle, t: Trapezoid, gray: Brick 4-fiftyPercent, dstFunc: DstFunc <- null]; 

Trapezoid: TYPE ■ record [ 

x: Interpolator, y: integer, - upper left 

w: Interpolator, — across top; must be positive 

h: natural]; 

GrayTrapezoid paints the trapezoid defined by t in window, gray and dstFunc act as in the 
procedure Gray. The trapezoid is defined in Figure 24.2 with the slope of the left side of the 
trapezoid being t.x.dVal and the slope of the right side of the trapezoid being t.x.dVai minus 
t.w.dVal. In Figure 24.2, t.x.dVal is minus one half and t.w.dVal is nine tenths. 




Figure 24.2 Trapezoid definition 



24.2.5 Painting Along Trajectories, SUf^g Window Contents 

Shift: PROCEDURE [window: window.Handle, box: window.Box, newPlace: window.Ptacel; 

Shift does a block move of a rectangular portion of window's current content. This 
operation does not invoke any client display procedures, box describes the region of 
window to be moved to newPlace. If Display does not have the pixels for a visible area of 
the destination box, that area is filled with trash and marked invalid. The client should 
validate the window when it has finished altering the window content. Shift does not 
invalidate the areas vacated by the move; if they are repainted, the client should invalidate 
them. If Shift is executed from within a display procedure, it does not clip the region 
painted to window's invalid area list. Invalid area lists are explained in the Window 
chapter. 
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Trajectory: pubuc procedure [ 

window: window.Handle, box: window.Box window.nuiiBox, proc: TrajectoryProc, 
source: long pointer ^ nil. bpi : cardinal 1 6, height: cardinal <- 16, 
flags: BitBit.BitBitFlags *- bitFlags, missesChiidren: boolean 4- false, 
brick: Brici(4-NiL]; 

TrajectoryProc: type - procedure [Handle] returns [window.BoxjNTEGER]; 

Trajectory repeatedly calls proc and paints a brush where proc specifies. The brush may be 
either a gray brick or a portion of the bitmap source. Trajectory avoids much of the 
overhead of successive calls to the normal Display routines, box is the window region in 
which painting may occur. The client must not try to paint outside box; this is not checked, 
flags controls the type of painting performed. If flags.gray ■ true, the gray brick is painted; 
otherwise, a bitmap is painted. Trajectory repeatedly calls proc for instructions. If proc 
returns a box having dims.w ■ 0 (such as window.nullBox), iteration ceases and Trajectory 
returns. Otherwise dims.w # 0; Trajectory paints the brush and then loops to call proc 
again. The bmsh paints the returned Box in the window as follows. If a gray brick is being 
painted, the brick completely fills the returned Box. If a bitmap is being painted, the 
bitmap starts at a bit offset of < integer > from source, is Box.dims.h high, and has bpi 
pixels per line. The client may wish to alter the brush content along the trajectory by 
having source be a large bitmap containing several different brush patterns and having 
proc return the bit offset and Box.dims of the desired portion. (BitBit.BitBitFlags are 
described in §24.2.2.) height and missesChiidren are unused, proc must not call any 
procedures in Display or Window; doing so will result in a deadlock. 

24.3 Usage/Examples 



24.3.1 Special Topic: Direct Painting 

As described in the Window chapter, the standard way for a client- to paint into its window 
is to update its data structures, invalidate the portion of its window that needs to be 
painted, and then call a window. Validate routine. Window responds by calling back into the 
client's display procedure to do the painting. 

The client may also paint directly into a window without going through window.Vaiidate. 
However, this direct-painting approach is subject to several pitfalls and system bugs. 
Clients commonly choose direct pednting only when high painting performance is required, 
such as dynamically extending an inverted selection while tracking the mouse or 
implementing a blinking caret. 

Pitfall 1: One consequence of doing direct painting is that the window's display procedure 
must not depend on Window clearing invalid areas for it. As described in the Window 
chapter, if clearingRequired » true, Window guarantees that when the display procedure 
is called to paint the window, all of the window's pixels that should be white indeed are 
white. In that situation, the window might contain any combination of its previous 
contents and erased areas. Notice that the following sequence of events might occur: 
Window clears invalid area; then the client direct paints into some part of the invalid area; 
then Window calls the window's display procedure. In this situation, the parallel direct- 
paint activity has voided Window's guarantee of the content of the invalid area. To 



24-8 



Viewpoint Programmer's Manual 



24 



handle this case, the display routine must erase or otherwise completely overpaint the 
invalid areas itself. 

Pitfall 2: A client can get into trouble when it wishes to change the state of the backing 
data being displayed within a display procedure and attempts to make the change by 
painting from the display procedure rather than by invalidating the affected area and 
painting later. The display procedure's paint is clipped to its invalid area list and thus fails 
to achieve the desired effect. There are several ways to solve this problem: 

• Do not change the backing data inside a display procedure. This approach matches 
nicely with the intended fimction of a display procedure. Do not expect a display 
procedure to change data— its job is to repaint. 

• Have the display procedure just invalidate the* areas affected by the data being 
changed. Because a validate is already in progress, it is not necessary to call 
Window. Validate. When the display procedure returns, it is called back with any new 
invalid areas that are waiting for it. 

• Have the display procedure call window.FreeBadPhosphorList before changing the 
data. This allows paint from the display procedure to affect the entire window, not 
just the invalid areas. 

24^ Example 1 

The program fragments below demonstrate the use of Display in a window's display 
procedure.. 

~ Enumerated TYPEs for displaying t/ie games baciiground. 
Background: TYPE ■ {gray, white}; 
background: Background gray; 

DisplayBoardSW: proc [window: windoMr.Handle] ■ { 
" This is the body window's display procedure. 
vLine, hUne: window.Box; 
left, right, top, bottom: integer; 

FindBounds: proc [window: window.Handle, box: window.Box] ■ { 
left ^MiN[left, box.place.x]; 
top 4-MiN(top, box.place.y]; 
right 4- MAx[right, box.place.x * box.dims.w]; 
bottom 4- MAx[bottom, box.place.y * box.dims.h]}; 

— Paint borders and baclcground. 

Dispiay.Black[window: window, box: boardAndBorderBox]; 
PaintBackground[window: window, box: boardBox]; 
vUne4-[upperLeft, [lineWidth,(boardSize-1)*unitH + 1]]; 
hUne 4- [upperLeft, [(boardSize - 1)*unitW ♦ 1, lineWidth]]; 
THROUGH [firstDimboardSize] oo 

Dispiay.Black[window, vLine]; 

Dispiay.Black[window, hLinej; 

vLine.place:x4-vLine.place.x * unitW; 
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hLine.place.y 4-hLine.piace.y * unitH; 

ENDLOOP; 



left 4- top 4~INTE6Elt.LAST; 

right bottom <-inte€ER.first; 
window.EnumeratelnvaiidBoxes[FindBounds] 

}; 

PaintBackground: PROC [window: window.Handle, box: window.Box] ■ { 
SELECT bacicground from 

gray « > oispiay.Gray[wjndow, box]; 
white a > Display .White[window» box]; 

ENOCASE 

}; 

PaintStone: RJBUCPROc[who: BlacicWhite, u, v: Dim, play: CARDINAL] » { 
center: window.Place; 
stoneBox: window.Box; 
numStr: string *- [3]; 

IF 'ValidCoordsCu, v] then return; 
center BoardToPlace(u, v]; 
StoneBox 4- [ 

place: [center.x - stoneRadius, center.y - stoneRadius], 
dims: [stoneSize, stoneSize]]; 

— paint a bitmap that represents game pieces. 

Display. Bitmap! 

window: boardSW, box: stoneBox, address: outerStone, 
bitmapBitWidth: stoneBpl, flags: Dispiay.palntFlags]; 

IF who • white THEN 

Dispiay.BitmapI 

window: boardSW, box: stoneBox, address: innerStone, 
bitmapBitWidth: stoneBpl, flags: eraseFtags]; 

}; 

CreateGoSWS: pubuc procedure [ 

reference: NSFit«.ReferenceRecord, name: Environm«nt.Block ] 

RETURNS [StarWindowShelLHandle] ■ { 

" This procedure is invoiced via a system menu, 
sz: StarWindowSh«ll.Handie; 



starwindowSheihSetPreferredDims [ sz, [592, 661] ]; 

— The display procedure is set here. .i0^ 
boardSW 4-starWindowSheii.CreateBody [ 
sws: sz. 
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repaintProc: Display BoardSW, 
bodyNotifyProc: TIPMe ]; 
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24.4 Index of Interface Items 
Item 

Arc: PROCEDURE 

BitAddress: type 

BitAddressFromPlace: procedure 
Bi'tBitFtags: type 
bitFtags: BitBit.BitBitFtags 
Bitmap: procedure 
Black: procedure 
BiackParallelogram: procedure 
boxFlags: BHBit.BitBitFiags 
Brick: type 
Circle: procedure 
Conic: procedure 
DasiiCnt: procedure 
OstFunc: type 
Ellipse: procedure 
eraseFlags: BitBit.BitBttFiags 
fiftyPercent: Brick 
FixdPtNum: type 
Gray: procedure 
GrayTrapezoid: procedure 
Handle: type 
Interpolater: type 
Invert: procedure 
Line: procedure 
LineStyle: type 
UneStyleObject: type 
paintBitFlags:BitBit.BitBltFlags 
paintFlags: BitBft.BitBltFlags 
paintGrayFiags: BitBit.BitBltFlags 
Parallelogram: type 

Point: PROCEDURE 

replaceboxFiags: BKBtt.BitBltFtags 
repiaceFlags: BHBit.BitBltFlags 
replaceGrayFlags: BitBit.BitBltFiags 

Shift: PROCEDURE 

textFlags: BitBit.BitBltFtags 
Trajectory: procedure 
TrajectoryProc: type 
Trapezoid: type 
White: procedure 
xorBoxFlags: BitBit.BitBltFlags 
xorFlags: BttBit.BitBltFlags 
xorGrayFiags: BitBit.BitBltFlags 
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25.1 Overview 

Divider maintains a table of entries in memory, each representing an icon. The entries may 
or may not be backed by files. Divider does not operate on these entries directly; it uses a 
Dhrider.ConvertProc and a Oivider.GenericProc associated with each entry. 

Also associated with each entry is an NSPite.Type used to identify the entry's 
Contain««.lmplementation, a label, and a pointer to instance-specific data for the entry. 

Associated with each divider when it is created is an NSFile.Type. Divider automatically sets 
a Containee.lmplementatlon for this file type that supports converting the divider to a file 
and opening the divider as a container window displaying the entries. 

Also associated with each divider is a CH.Pattern specifying a clearinghouse domain and 
organization. It is inherited from a parent divider and is passed to all entries through the 
Oivtder.ConvertProc and the Oivid«r.GenericProc associated with each entry. When the 
divider is converted to a file, the pattern is automatically encoded in an attribute of the file. 

25.2 Interface Items 

25.2.1 Creating and Destroying 

Handle: type « long pointer to Object; 

Object: type; 

Create: procedure [ 
type: NSFUe.Type, 
name: xstring.Reader, 

initialSize: cardinal «~oivider.defauitlnitialSize, 
Increment: cardinal <-Divider.defaultlncrement, 
zone: uncounted zone nil] 
RETURNS [handle: Handle]; 
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Create creates a divider, type specifies the NSFil«.Type the divider has if it is converted to a 
file. A Contain««.lmplementation is automatically set for this type, name specifies the name 
of the divider. It appears in the window header when the divider is opened, and it is the 
name of the file if the divider is converted to a file. The xstring. Reader bytes are copied. The 
divider is created with a table large enough to hold initialSize entries. If an entry is added 
when the table is full, the table grows by increment entries. Storage for the divider is 
allocated from zone. If zone is defaulted, storage is allocated from a heap maintained by 
Divider. 

Destroy: procedure [handle: Handle]; 

This releases all storage associated with the given divider, handle is no longer valid when 
this procedure returns. 

25*2.2 ConvertProc and GenericProc 

ConvertProc: type - procedure [ 
data: long pointer, 
pattern: CH.Pattern, 
target: s«i«ction.Target, 

zone: UNCOUNTED ZONE, 

info: s«i«ctionXonversionlnfo <- [convertQ]] 
RETURNS [value: Selection. Value]; 

A ConvertProc is the same as a Seiection.ConvertProc except that it has the extra argument, 
pattern, that specifies a clearinghouse domain and organization. (See the Selection 
interface for the definition of the other arguments.) Whenever the divider is requested to 
convert one of its entries, it calls the ConvertProc associated with an entry, with pattern 
set to the domain and organization associated with the divider, 

GenericProc: type « procedure [ 
atom: Atom.ATOM, 
data: longpointer, 
pattern: CH.Pattern, 

changeProc: Containee.ChangeProc 4-niu 
changeProcData : lono pointer nil] 

RETURNS [long UNSPECIFIED]; 

A GenericProc is the same as a Containee. GenericProc except that it has the extra argument, 
pattern, that specifies a clearinghouse domain and organization. (See the Containee 
interface for the definition of the other arguments.) Whenever the divider is requested to 
operate on one of its entries, it calls the GenericProc associated with an entry, with pattern 
set to the domain and organization associated with the divider. 

DividerConvertProc: ConvertProc; 

DividerGenericProc: GenericProc; 

These procedures may be associated with entries that themselves are dividers. In this case 
the Handle associated with the divider should be provided as the instance-specific data 
handle. See below for an example of a divider contained in another divider. 
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25.2.3 Adding and Finding Entries 

AddEntry: procedure [ 
handle: Handle, 
type: NSFito.Type, 
label: xstring.Reader, 
data: long pointer nil, 
convertProc: ConvertProc ^hil, 
genericProc: GenerlcProc <- nil]; 

AddEntry adds an entry to the divider speciHed by handle, type obtains the 
GmtainM.lmplementatlon for the entry, label is used to label the entry in the divider's 
container window. The xstring. Reader bytes are copied, data is item-specific data for the 
entry that is passed to the ConvertProc and GenericProc associated with the entry. If 
convertProc or genericProc is defaulted, the divider uses the corresponding procedure in 
the entry's ContaiiM«.lmpiementation. 

FindEntry: procedure (handle: Handle, type: NSFii«.Type, 
label: xstring.Reader] 

RETURNS (found: boolean, entryOata: long pointer]; 

FindEntry finds the entry in the divider handle with the specified type and label, found 

indicates whether the item was in the divider. entryOata is the data associated with the 
entry, ifit was found. FindEntry is defined in DividerExtra.mesa. 

FindOrAddEntry: procedure (handle: Handle, type: NSFite.Type, 
label: xstring.Reader, data: long pointer nil, 
convertProc: ConvertProc <- nil, 
genericProc: GenericProc nil] 
RETURNS (found: BOOLEAN, entryOata: long pointer]; 

FindOrAddEntry finds the entry in the divider handle with the specified type and label, 
and adds an entry if it was not found, found indicates whether the item was in the divider. 
entryOata is the data associated with the entry, if it was found. FindOrAddEntry is defined 
in DividerExtra.mesa. 

25.3 Usage/Examples 

25.3.1 Fragment from Directory ImpLmesa 

This fragment is from Oirectorylmpl.mesa, which implements the Directory interface. It 
shows the implementation of oirectory.AddOividerEntry and the mainline code to create the 
top-level directory dividers. See the CHOivider interface for more examples. 

- File types for the directory Implementation — 
directory: starFiieTypes.FileType ■ ...; 
folder: starFii«Types.FileType ■ ...; 
workstation: starFtieTyp«s.FileType ■ ...; 
user: StarFiieTypes.FileType « 
domain: starFUeTypes-FiieType ■ 



25-3 



Divider 



- The reference for the prototype folder— 
prototypeReference: NSFiie.Reference ^ 

- Handles for the top-level dividers ~ 

dividers: array oirectory.DividerType op oividw.Handle Aa [nil]; 

AddDividerEntry: pubuc procedure [ 
divider: oirtctory.DividerType, 
type: NSFii«.Type, 
label: xstring.Reader, 
data: lon<3 pointer nil, 
convertProc: oivider.ConvertProc 4-nil, 
genericProc: oividcr.GenericProc ^ nil] ■ 
begin 

Divider .AddEntry [ 

handle: dividers(divider], 

type: type. 

label: label, 

data: data, 

convertProc: convertProc, 
genericProc: genericProc]; 

end; 

. •» Create the top-level dividers (top will back the directory icon) 
dividers[top] 4- Divider.Create [directory, stringOirectory]; 
dividers[ws] 4-Divider.Create [workstation, stringWorkstation]; 
dlviders[user] Divider.Create [user, stringUserj; 

~ Insert the workstation divider into the directory — 
Dir«ctory.AddDividerEntry [ 

divider: top, 

type: workstation, 

label: stringWorkstation, 

data: dlviders[ws], 

convertProc: Dividar.DividerConvertProc, 
GenericProc: Divid«r.DividerGenericProc]; 



- Insert the user divider into the directory 
Dir«ctory.AddDividerEntry [ 

divider: top, 

type: user, 

label: stringUser, 

data: dividers[user], 

convertProc: Divider.DividerConvertProc, 

genericProc: oivider.DividerGenericProc]; 



- Insert the prototype folder into the workstation divider — 
" (Note: this is an actual file that will use the folder implementation) - 
Dir«ctory.AddDividerEntry [ 
divider: ws. 
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type: folder, 

label: stringPrototypes, 

data; @prototypeReference]; 
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25.4 Index of Interface Items 
Item 

AddEntry: procedure 
ConvertProc: type 
Create: procedure 
Destroy: procedure 
oi«id«r.ConvertProc:TYPE 
DividerConvertProc: GinvertProc 
OividerGenericProc: GenericProc 
FindEntry: procedure 
FindOrAddEntry: procedure 
GenericProc: type 
Handle: type 
Object: type 
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26.1 Overview 

Viewpoint provides a facility that permits clients to register procedures that are to be 
called when specified events occur. For example, a client may wish to be notified whenever 
a document is closed, or perhaps just the next time a document is closed. Clients need not 
know which module can cause the event. 

26.2 Interface Items 

26.2.1 Registering Dependencies 

A client wishing to be notified of some future event calls either AddDependency or 
AddDependencies, specifying the EventType and an AgentProcedure to be called when the 
event occurs. Note: ViewPoint need not know in advance what EventType is implemented, 
nor which modules implement them. 

AddDependency: procedure [ 
agent: AgentProcedure, 
myData: long pointer to UNSPEaPiEO, 
event: EventType, 
remove: FreeDataProcedure 4-NiL] 
RETURNS [dependency: Dependency]; 

AddDependencies: procedure [ 
agent: AgentProcedure, 
myData: long pointer to unspeofied, 
events: long descriptor for array of EventType, 
remove: FreeDataProcedure nil] 
RETURNS [dependency: Dependency]; 

AgentProcedure: type ■ procedure [ 
event: EventType, 

eventData, myData: long pointer to unspeofied] 
RETURNS [remove, veto: boolean <- false]; 
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FreeOataProcedure: type ■ procedure [mydata: long pointer to unspecified]; jgnii^ 
Dependency: type [2]; -- Opaque — 

A dependency may be added to an event or an entire set of events by calling 
AddDependency or AddDependencies. Both of these procedures return a private type, 
Dependency, that uniquely identifies that set of dependencies. The value returned may be 
saved and subsequently used in a call to RemoveDependency, which removes the 
dependency or dependencies associated with the earlier AddXXX call. The AgentProcedure 
may also remove the dependency, as discussed below. 

When the specified event occurs, agent is called with the EventType, the eventData for the 
event, and the client data passed as myData. If a client wishes to veto the event (for 
instance, to disallow a world-swap), its AgentProcedure should return veto: true. This 
aborts the notification; that is, no other clients dependent on the event are notified. 
However, there is no guarantee of the order in which multiple clients are notified. If any 
client vetoes the event, the call to Notify returns true. There is no way to prevent a client 
from vetoing; instead, implementors of events that should not be vetoed should raise an 
ERROR if Notify returns TRUE. To remove its dependency on an event, a client's 
AgentProcedure should return remove: true. If the dependency is removed and a 
FreeDataProcedure was provided, it is called at this time to allow the client to free any 
private data. 

EventType: type ■ Atom.ATOM; 

The ATOM (strings) used to identify different events must of course be distinct. The 
following examples are possibilities of how this could be managed. (1) By a central 
authority whose job it is to guarantee uniqueness of EventTypes. This could be the same 
person in charge of other such allocations, such as NSFiie types. (2) By a hierarchical 
naming structure, msmaged by a distributed authority. (3) By a file that lists all known 
EventTypes within a given system; this file is managed by the Librarian to ensure against 
parallel allocation of new EventTypes. (In effect, this is the same as case 1, but the 
Librarian takes the place of the central authority. ) 

RemoveOependency: proc Idependency: Dependency]; 

NoSuchDependency: error; 

If RemoveOependency is called with a Dependency that is invalid (possibly because the 
dependency has already been removed), it raises the error NoSuchDependency. 

26.2.2 Notification 

Notify: procedure [event: EventType, eventData: long pointer to unspecified ^ nil] 
RETURNS [veto: boolean]; 

When the event occurs, the implementor calls Notify, giving it the EventType for the event 
and any implementation-specific data (eventData) required by the client. (Presumably it is 
uncommon for a single operation to wish to Notify more than one event; this is why Notify 
does not take an array argument.) The Event interface then invokes each AgentProcedure 
that is dependent on the EventType. Each AgentProcedure is given the 
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EventType causing the notification, the client data provided when the dependency was 
created, and the eventOata given by the impiementor in the call to Notify. 

26.3 Usage/Examples 

The Event database is monitored to disallow changes while a Notify is in progress. An 
AgentProcedure is allowed to call Notify; that is, one event may trigger another. However, 
an AgentProcedure must not call AddDependency or RemoveOependency, or deadlock 
will result. Because it is relatively common for an AgentProcedure to wish to remove its 
own dependency, the AgentProcedure can return remove: true to cause the dependency to 
be removed. If the dependency was added via AddDependencies, then all of the 
dependencies created by that call are removed. The dependency is removed even though 
some later client of the same event might choose to veto the event. (If an earlier client has 
already vetoed, of course, then this AgentProcedure never gets called.) If an application 
requires that a dependency be removed only if the event is not vetoed, the impiementor can 
notify a second event that informs clients whenever the first event is vetoed. 

Three notes regarding the preceding paragraph: First, an AgentProcedure may get called 
twice even if it always returns remove: true because two separate processes may be doing 
parallel calls to Notify. Once an AgentProcedure returns remove: true, no subsequent 
calls to Notify invoke that dependency, but any parallel calls in progress complete 
normally. Second, because an AgentProcedure might be invoked at any time, it is a bad 
idea to call Add/RemoveOependency from within a private monitor, lest it lock trying to 
modify the Event database while a Notify is inside the AgentProcedure trying to grab the 
lock. However, the Notify call may very well be within the implementor's monitor, which 
means the AgentProcedure's use of the eventOata is typically limited. Finally, if an 
AgentProcedure needs to call Add/RemoveOependency, it may get the desired effect by 
FORidng the call so that it takes place shortly after the Notify already in progress. 

26.3.1 Example 1 

— Module interested in an event 

eventType: Ev«nt.EventType 4-Atoin.MakeAtom [''SampleEvent''L]; 

EventAction: Evant^AgentProcedure ■ { 
- Do appropriate thing for eventType }; 

Ev«nt.AddDependency [ 
agent: EventAction, 
my Data: nil, 
event: eventType]; 

— Module that signals the event 

eventType: Event. EventType <-Atom.MakeAtom ["SampleEvenfU; 
eventOata: — Relevant info, a record, a window handle, etc. — ; 



[] <- Event.Notify [event: eventType, eventOata: eventOata]; 
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26.3.2 Example 2 

— Declare event and eventOata 
desktopWindowAvailable: Ev«nt.EventType; 
desktopWindowHandle: window.Handle <-nii.; 

— Declare AgentProcedure" 
Startup: EwntJKgentProcedure • { 

If eventOata - nil then return [veto: true]; 
desktopWindowHandle eventOata }; 

" Register event— this is mainline code " 

Q 4-Ev«nt.AddOependency [Startup, nil, desktopWindowAvailable]; 

In Desktop code, another module, notify occurrence of the event-' 
U «->Ev«nt.Notify [desktopWindowAvailable, window]; 
— Window Is desktop window — 
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26.4 Index of Interface Items 



Item Page 

AddDependendes: procedure 1 

AddOependency: procedure 1 

AgentProcedure: type 1 

Dependency: type 2 

EventType: type 2 

FreeOataProcedure: type 2 

NoSuchOependency: error 2 

Notify: procedure 2 

RemoveOependency: procedure 2 
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27.1 Overview 

FHeContainerSheil provides a simple way to implement a container application that Is 
backed by an NSFtie. FiieContainerSheil takes an NSFiie and column information (such as 
headings, widths, formatting) and creates a FileContainerSource, a StarWindowSheil, and 
a ContainerWindow body. (See also the FiieContainerSource, ContainerSource, 
StarWindowSheil, and ContainerWindow interfaces). Most NSFiie-backed container 
applications can use this interface, thereby greatly simplifying the writing of applications 
such as Folders and File Drawers. 

27.2 Interface Items 

27.2.1 Create a FiieContainerSheil 

CreateX3: procedure [ 
file: NSFito.Reference, 

columnHeaders:contain«rWindow.ColumnHeaders, 
coiumnContents: Fii«Contain«rSourc«.ColumnContents, 
reguiarMenultems.topPusheelVlenultems: M«nuOata.ArrayHandie <-niu 
scope: NSFiia.Scope *- [], 

position: Contain«rSourc«.ltemindex 4~ 0, 
options: FlieContainerSource.Options 4- [], 

access: Contain«rWindowExtra3.Access 4- ContainarWindowExtraJ.full Access, 

considerShowingCoverSheet: boolean] 
RETURNS [shell: StarWindowShelLHandle]; 

CreateX: procedure ( 
file: NSFiie.Reference, 

columnHeaders:containerWindow.ColumnHeaders, 
coiumnContents: FileContainarSource.ColumnContentSr 
regularMenultetns,topPusheeMenultems: M«nuOata.ArrayHandle 
scope: NSFiie.Scope ^ [], 

position: ContainerSource.itemlndex 4—0, 
options: FileContainarSource. Options [], 
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access: ContainerWindowExtra3.Access 4~ContajnerWindow£xtra3.fuilAccess] 
RETURNS [shell : StarWindowSheli.Handle]; 

Create: procedure [ 
file: NSFito.Reference, 

columnHeaders:contain«rWindow.ColumnHeaders, 
columnContents: Fii«contain«rSourc«.ColumnContents, 
regularMenultemSftopPusheeMenultems: M«nuOata.ArrayHandle 
scope: NSFito.Scope 4- U, 

position: ContainerSourcs.ltemlndex 4~ 0, 
options: Fii«Cofitain«rSourc«.OptionS 4- Q] 
RETURNS [shell : starWindowSh«ii.Handle]; 

Create, CreateX, and CreateX3 create a StarWindowSheli with a container window as the 
body window, file is the backing for the container; it must be an NSFile with children. 
columnHeaders and columnContents specify all the necessary information about the 
columns to be displayed for the open container. (See the ContainerWindow and 
FileContainerSource interfaces for the specifics of the headers and contents.) scope 
specifies ordering:, filtering, and direction, if any. position indicates the item that should be 
displayed first, access speciHes the ContainerWindow access. (See the ContainerWindow 
interface for details. regularMenuitems and topPusheeMenultems are the menu items 
that the client would like to put in the header of the StarWindowSheli. Create puts these 
, items in the header along with its own menu items, such as Show Next and Show Previous. 
considerShowingCoverSheet specifies whether the resulting shell will be allowed to have 
a coversheet. true means that the shell will have a coversheet if one is define; false means 
that the coversheet will not be shown and the menu item "Show Coversheet" is not ?^*% 
displayed. Fine point: The client is responsible for putting any bottomPusheeCommands in the window 

header. CreateX is defined in FileContainerShellExtra.mesa, CreateXS is defined in 
FileContainerShellExtraS.mesa 

27.2.2 Operations on the Shell 

GetContainerWindow: procedure [shell: starWindowSh«ii.Handle] 
RETURNS [window: window.Handle]; 

Returns the container window that was created by the Create procedure. May raise 
Contain«rWindow.Error[notAContainerWindow] if the shell does not have a container 
window in it. 

GetContainerSource: procedure [shell: starWindowSheii.Handle] 
RETURNS [source:contain«rSourca.Handle]; 

Returns the container source that was created by the Create procedure. May raise 
ContainerWindow.Error[notAContainerWindow] if the shell does not have a container 
window in it. 
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27.3 Usage/Examples 

27.3.1 Example: Creating a FileContainerShell and Specifying Columns 

The following example presents the procedure CreateFileSWS, which takes an 
NSFiie. Reference and creates a file container shell with two columns: the name of the file 
and a version date. (See the ContainerSource interface for details on columns.) The name 
column uses the predefined Contain«rSource.NameCoiumn; the version column is given in the 
example. The version column differs from the standard ContaincrSourca.DateCoiumn in that 
it displays the last modified date for directories instead of — . 



ContentSeq: type ■ record [ 

SEQUENCE cols: CARDINAL OF FiitCofitaincrScurce.CoiumnContentslnfo]; 
HeaderSeq: type ■ record [ 

SEQUENCE COis: CARDINAL OF ContainerWindow.CoiuiTinHeaderinfo]; 

NumberOfColumns: CARDINAL ■ 2; 

Z: UNCOUNTED ZONE ■ 

CreateFiieSWS: procedure [reference: NSFii«.Reference] 

RETURNS [StarWindowStMlLHandle] a 
BEGIN 

shell: starwindowSh«ii.Handle: 

headers: long pointer to HeaderSeq «- MakeColumnHeadersQ; 
contents: long pointer to ContentSeq <- MakeColumnContentsQ; 
shell FileContainerShell.CreateC 
file: reference, 

columnHeaders: OESCRiPTOR[headers], 

columnContents: OESCRiPTOR{contents]]; 
z.FREE(@headers]; 
z.FREE[@contents]; 
RETURN[shelll; 
end; 

DateFormatProc: FitoContaincrSourct.MultlAttributeFormatProc ■ 

BEGIN 

If non-directory, show createdOn date. For directory, s/iow last date modified 
(the last time anything was changed in directory) 
template: xstring. Reader Body <- 

xstring.FromSTRINGr<2>.<6>-<4> <8>:<9>:<10>"L]; 
xTimtt.Append[ 
displayString, 

iFattrRecord.isOirectory then attrRecord.modifledOn else attrRccord.createdOn, 
©template]}; 
end; 

MakeColumnContents: procedure 

RETURNS [columnContents: long pointer to ContentSeq] ■ 
begin 

dateSelections: NSFiie.Seiectlons ^ [interpreted: [ 

isOirectory: true, createdOn: true, modifiedOn: true]]; 
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coiumnContents 4- z.NEW[ContentSeq[NumberOfColumns]; 
coiumnContentsfO] *- FileContainerSource.NameCoiumnn; 
coiuinnContents[1] 4-[muitipleAttributes [attrs: dateSelections, formatProc: 
OateFormatProc]] ; 
RETURN [coiumnContents]; 
end; 

MakeCoiumnHeaders: PRoaouRE 
RETURNS [coiumnHeaders: long pointer to HeaderSeq] ■ 

BEGIN 

coiumnHeaders <~ z.NEW(HeaderSeq[Numi3erOfCoiumns]]; 
coiumnHeaders(0] 4-[ 
width: 367, 

heading: XString.FromSTRING["NAME"] ]; 
coiumnHeaders[1] 4»[ 
width: 135. 

heading: xstring.FromSTRING("VERSION OF"] ]; 
RETURN [coiumnHeaders]; 
end; 
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27.4 Index of Interface Items 



Item Page 

Create: procedure 1 

CreateX: procedure 1 

GetContainerSource: procedure 2 

GetContainerWindow: procedure 2 



27 FileContainerShell 
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28.1 Overview 

FtieContainerSource supports the creation of NSFile-backed container sources (see 
ContainerSource). It also provides facilities for specifying the columns that will be 
displayed for each item in the source. 

FileContainerSource implements all of the procedure types described in the 
ContainerSource interface, as well as ail the procedures described below. 

28.2 Interface Items 
28^2.1 Creation 

Options: TYPE ■ RECORD [ 

readonly: boolean <- false]; 

Create: procedure [ 
file: NSFiic.Reference, 
columns: ColumnContents, 
scope: NSFii«.Scope <- Q, 
options: Options U ] 

RETURNS [source: ContainerSourccHandle]; 

OeateX: procedure [ 
file: NSFiie.Reference, 
columns: CoiumnContents, 
scope: NSFiie.Scope <- [], 
options: Options *- [] ] 

RETURNS [source: ContainerSource.Handle, sourceX: ContainerSourceExtra.Procedures]; 

Creates a container source backed by file, which must be an NSFile with children, columns 
describes the information that should be displayed for each entry in the container, columns 
is copied by this procedure, so the client may release any storage associated with columns 
after calling Create, scope specifies the range of files that will be displayed. The caller of 
Create is responsible for the storage in the scope parameter; FileContainerSource will not 
copy it. It can be destroyed at the same time the source is destroyed. Typically the client 
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will save the pointer to scope storage in same place as source handle, options specifies 
global information about the container source. Display formatting is managed by the 
container window. (See the ContainerWindow and FileContainerSheii interfaces.) CreateX 
is identical to Create, except that it returns the additional Contain«rSoureeExtra.Procedures 
needed for concurrency. (See the ContainerSource chapter for details on these procedures). 
FiiM point: Craat«X is exported by Fti«Contajn«rSourceExtra3. 



28.2.2 Specifying Columns 

When a Gle container source is created* columns may be specified. Each column represents 
information that will be displayed for each item. The container window requests the 
columns one at a time in the form of strings. In a file container source, each column must be 
based on some combination of NSFiie attributes. For each column, the creator of file 
container source specifies which attributes are required to format a string for that column 
and supplies a procedure that will be called with the specified attributes. When the files in 
the source are enumerated, the procedure for a particular column is called with the values 
of the specified attributes for each file, which should be used to generate the string for that 
file. 

ColumnContents: type ■ 

LONG OESCRtPTOR FOR ARRAY OF CoiumnContentslnfo; 

ColumnContents des^cribes a set of columns, where each column is some information that is 
displayed for each item in the container display. The columns are displayed in the order 
given by this array. 

CoiumnType-.TYPE « {attribute, extended Attribute, multipleAttributes}; 



CoiumnContentslnfo: type ■ record [ 
info: SELEcrtype: CoiumnType from 
attribute ■ > [ 

attr: NSFii«.AttributeType, 

formatProc: AttributeFormatProc 4~nil], 
needsOataHandie: boolean false], 

extendedAttribute ■ > [ 

extendedAttr: NSFiio.ExtendedAttributeType, 

formatProc: AttributeFormatProc nil, 
extendedAttribute ■ > ( 

extendedAttr: NSFUe.ExtendedAttributeType, 

formatProc: AttributeFormatProc 4-nil], 
multipleAttributes ■ > [ 

attrs: NSFUe.Selections, 

formatProc: Multi AttributeFormatProc 4- nil], 
enocase]; 



CoiumnContentslnfo describes a single column of information that can be displayed for 
each item in a container display. Each column may be backed by one of three things: an 
NSFiie interpreted attribute (the attribute variant), and NSFiie extended attribute (the 
extendedAttribute variant), or some combination of several attributes (the 
multipleAttributes variant). The attribute and extendedAttribute variants both take a 
specification of what attribute is being described (attr and extendedAttr) and an 
AttributeFormatProc that is called to render the attribute as a string. If needsOataHandie 
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■ TRUE, then a valid Containee.OataHandle is passed to the format procedure as the 
containeeOata parameter, else the containeeOata parameter is nil. If the column needs a 
Containee.OataHandle in order to format it, then needsOataHandle should be true. This 
addition is for performance: obtaining a Contain««.OataHandi€ requires an extra access to 
the file, thus slowing up the enumeration. The multipieAttributes variant is for columns 
that may require more than one attribute. (The typical example is the SIZE column in 
folders, in which some items display the numberOfChlldren attribute and others display 
the sizelnPages attribute, depending on the isOirectory attribute.) attrs specifies all the 
attributes required for this column. formatProc is the procedure that will be called to 
format the column. 

See the common types of columns provided below in the section on commonly used columns. 

AttrlbuteFormatProc: type ■ procedure [ 
contai neelmpi : Containee.lmplementation, 
containeeOata: Containee.OataHandle, 
attr: NSFiie.Attrlbute, 
dIspiayStrIng: xstring. Writer]; 

When the container display mechanism displays a column that represents an NSFile 
attribute, it calls the AttrlbuteFormatProc specified for that column, attr contains the 
attribute to be formatted for display. displayString is used to return a formatted string that 
represents the desired attribute, containeelmpi may be used to make calls on the 
underlying implementation of the item being displayed. 

MulttAttributeFormatProc: type « procedure [ 
containeelmpi: Containee.lmplementation, 
containeeOata: Containee.OataHandle, 

attr Record: NSFiie. Attributes, LOiVG POfwrfirroNSFiie.AttributesRecord 
displayString: xstring. Writer]; 

When the container display mechanism displays a column that represents multiple NSFile 
attributes, it calls the MultiAttributeFormatProc specified for that column. attrRecord 
contains the attributes to be formatted for display. displayString is used to return a 
formatted string that represents the desired attribute, containeelmpi may be used to make 
calls on the underlying implementation of the item being displayed. 

28.2.3 Operations on Sources 

Getltemlnfo: procedure [ 

source: ContainerSource.Handle, itemlndex: ContainerSource.ltemlndex] 
RETURNS [flle:NSFiie.Reference.type: NSFiie.Type]; 

Returns an NSFile. Reference and type for the specified item. 

Info: PROCEDURE [source: ContainerSource.Handle] 
RETURNS [ 

file: NSFiie.Reference, 
columns: CoiumnContents, 
scope: NSFiie.Scope, 
options: Options]; 
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InfoX: proceoure[ 

source: ContainerSource.Handle] 

RETURNS [sourceX: ContainerSourcsExtra.Procedures]; 

The Info procedure returns information about a file container source; the information 
returned is the same information that was used to create the source (see the Create 
procedure). If the source was created using CreateX, InfoX returns the extra procedures 
defined in ContaiMrSour<«Extra.PrOcedures. Fln« point; InfoX is defined in ContaimrSourceExtra. 

ISit: PROCEDURE (sOUfCe: Contain«rSour€«.Handle] RETURNS [BOOLEAN]; 



Isit returns true if source is a file container source. 



ChangeScope: procedure [source: ContainerSource.Handle, newScope: NSFiie.Scope]; 

Allows the scope (passed in to Create) to be changed. A call to ChangeScope is tjrpically 
followed by a source.ActOn[relist], then a Containerwindow. Update. 

Rebuildltem: procedure [source: ContainerSource.Handle, item: ContainerSource.itenfllndex],* 

Rebuiidltem causes the FileContainerSource to rebuild Item, for example after a client has 
changed an attribute that is displayed in a column of the source. Note that the client must 
call the appropriate ChangeProc in order to get the ContainerWindow to repaint properly. 
Fine point: Rebuildttem is exported by FiieContainerSourceExtra2. 

SourceEnumPrOC: type - procedure [source: ContainerSource.Handle] 
RETURNS [stop: BOOLEAN 4- false]; 

EnumerateSources: PROCEDURE [enumProc: SourceEnumProc]; 

EnumerateSources will enumerate all existing FileContainerSources and call enumProc 
with each source. The enumerate will stop early if the enumProc sets stop to true. Fine 
point: EnumerateSources and SourceEnumProc are defined in FileContainerSourceExtra3. 

TakeFilterProc: type » PROCEDUER[fs: ContainerSource.Handle,aboutToTake: NSFiie.Reference] 
RETURNS [ok: boolean]; 

SetTakeFilterProc: procedure : [fs; ContainerSource.Handle, p: TakeFilterProc]; 

Clients can use SetTakeFilterProc to set a TakeFilterProc that will be called just before each 
file is about to be moved or copied into the source. The TakeFilterProc returns a boolean; if 
ok is TRUE, the move or copy goes ahead, otherwise that file is not copied/moved into the 
source and the enumeration continues on to the next file. No message is posted if the 
TakeFilterProc vetos the copy, so feedback is up to the client. This procedure is provided to 
allow clients some control over what files are copied into the source; clients may use this to 
make sure their source only gets files of certain types. This proc has no effect on copies onto 
the closed container; clients must set up a separate filter mechanism for that case. For Bws 
4.3, these two procedures are in FtieContainerSourceExtra4. 
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28.2.4 Commonly Used Columns 

These predefined procedures csm be used in building a CoiumnContents array. 

IconColumn: procedure 

RETURNS [attribute CoiumnContentslnfo]; 

IconColumn represents a column with a small icon picture in it. The small picture is 
obtained from the containeelmpLsmailPicture that is passed in. 

NameCoiumn: procedure 
RETURNS [attribute CoiumnContentslnfo]; 

NameCoiumn represents a column with the file's name in it. 

SizeColumn: procedure 

RETURNS [multipleAttributes CoiumnContentslnfo]; 

SizeColumn represents a column with the file's size in it, as follows: If the file has the 
isOirectory attribute, the numberOfChildren attribute is displayed with the label 
''Objects"; if the file does not have the isOirectory attribute, the sizelnPages attribute is 
displayed with the label "Disk Pages**. 

DateColumn: procedure 

RETURNS [multipleAttributes CoiumnContentslnfo]; 

DateColumn represents a column with the file's creation date in it, as follows: If the file 
has the isDi rectory attribute, dashes ( — ) are displayed; if the file does not have the 
isDirectory attribute, the createDate attribute is displayed. 

VersionColumn: procedure 

RETURNS [attribute CoiumnContentslnfo]; 

VersionColumn represents a column with the file's version in it. VersionColumn is defined 
in FileContainerSourceExtra.mesa. 

NameAndVersionColumn: procedure 
RETURNS [multipleAttributes CoiumnContentslnfo]; 

NameAndVersionColumn represents a column with the file's name and version appended 
together with an exclamation point in between, e.g. Foo!3. NameAndVersionColumn is 
defined in FileContainerSourceExtra.mesa. 



28.3 Usage/Examples 

28.3.1 Example: Specifying Columns using FileContainerSource 

The following example presents the procedure MakeFolderLliceSheil, which takes an 
NSFile.Reference (Containee.DataHandle) and creates a file container shell with the 
number of columns dependent on some internal procedures. (See the ContainerSource 
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interface for details on columns.) The columns use the predefined columns such as 
ContainerSource.NameColumn. 

Columns: type ■ {icon, name, version, nameAndVersion, size, createOate}; 
HeaderSeq: type ■ record {sequence cois: cardinal of contaiiMrwindow.CoiumnHeaderinfo]; 
ContentSeq: TYPE ■ record ( 

sequence coIs: CARDINAL OF Fii«Contain«rSourc«.CoiumnContentslnfo]; 
ColumnArray:TYPE ■ array {icon, name, version, size, date} of cardinal; 
columnWidths: long pointer to CotumnArray 4- z.NEw[CoiumnArray null]; 



OientsGenericProc: Contain««.GenericProc ■ 
< < [atom: Atom.ATOM, 
data: contaiiMcOataHandle, 
changeProc: ContainM.ChangeProc 4-nil, 
changeProcOata: long pointer 4- nil] 

RETURNS [long UNSPECIFIED] > > 
BEGIN 

SELECT atom FROM 
open u > RETURN [ 

IVIalceFoiderUI<eShell [ 
data: data, 

changeProc: changeProc, 
changeProcOata: changeProcOata] ]; . 



ENDCASE a > RETURN [ oidFolder.genericProc [atom, data] ]; 
end; 

FreeColumnContents: pubuc procedure [coiumnContents: long pointer to ContentSeq] ■ 

BEGIN 

z.FREE[@columnContents]; 
end; 

FreeColumnHeaders: public procedure [columnHeaders: long pointer to HeaderSeq] • 

BEGIN 

z.FREE[@columnHeaders]; 
end; 

MalceFoiderLilceSheil: procedure [ 
data: containM.OataHandle, 
changeProc: Contain««.ChangeProc 4-nil, 
changeProcOata: long pointer nil] 

returns [shell: StarWindowShelUHandie] ■ { 

file: NSFUtt.Reference; 

columnHeaders: long pointer to HeaderSeq ^ MakeColumnHeaders[]; 
coiumnContents: long pointer to ContentSeq 4-MakeColumnContents[]; 



mydata: Oata z.new [DataObject «- [ 
cd: data. 
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changeProc: changeProc, 
changeProcData: changeProcOata]]; 
isLocai: boolean; 

BEGIN ENABLE 
UNWIND ■ > { 

z.FREE[@nnydata]; 

FreeColumnHaadars [columnHeaders]; 
FreeGilumnContents [columnContents]; 

}; 



shell 4-FiieContaiiMrSheil.Create [ 

file: file, 

columnHeaders: OESCRiPTOR(columnHeaders], 

columnContents: OESCRiPTOR(columnContents], 

regularMenultems: if "IsLocal then remoteRegularMenultems else nil]; 

IF shell ■ NIL THEN RETURN [shell]; 

starvvifidovtfSiwii.SetlsCloseLegalProc [shell. Cosing]; 
Cont«xt.Create[context, mydata. DestroyContext, shell]; 
FreeColumnHeaders [columnHeaders]; 
FreeColumnContents [columnContents]; 
StarvvindowSh«ii.SetPreferredDims [ shell, [700, 0] ]; 

RETURN [shell]; 
end; - ENABLE 
} 

MakeColumnContents: public procedure returns [columnContents: long pointer to 
ContentSeq] ■ 
begin 

i: integer 4- -1; 

columnContents <- z.NEw[ContentSeq[CountColumns(]]]; 
IF Showlcon[] then 

columnContents[i 4- i * 1] 4-Fil«Contain«rSour<a.lconColumn[]; 
— Procedures called below are not neccessary to the example. 
columnContents[i 4- i + 1]«- 

ip ShowNameAndVersionQ 

then Fii«ContairMrSourc«Extra.NameAndVersionColumn[] 

ELSEFil«ContainerSourc«.NameColumn(]; 

iFShowVersion[] then 

columnContents[i 4- i + 1] 4-Fii«ContainerSourceExtra.VersionColumn[]; 
iFShowSize[]THEN 

coiumnContents[i 4- i * 1] 4-FH«ContainerSourc«.SizeColumn[]; 
IF ShowCreateOate(] then 

columnContents[i 4- i + 1] 4-Fii«containerSource.DateColumn[]; 
return [columnContents]; 
end; 
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28.4 Index of Interface Items 



Item 
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AttributeFormatProc: type 


3 


ChangeScope:pROCEOURE 
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CoiumnContents: type 
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Create: procedure 
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CreateX: procedure 
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S 
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konColumn: procedure 
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Info: procedure 
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InfoX: procedure 
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ISit: PROCEDURE 
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Multi AttributeFormatProc: type 
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5 


Options: TYPE 
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Rebuildltem: procedure 
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SizeCoiumn: procedure 
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SourceEnumProc: procedure 
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VersionColumn: procedure 
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29.1 Overview 

The Form Window interface provides clients the ability to create and manipulate form 
items in a window. 

There are several types of items, each of which serves a different purpose and behaves 
differently for the user. All items except tagonly and command have a current value that 
can be obtained and set by the client and user. The user obtains the current value of an 
item by simply looking at it and sets the current value of an item by pointing at it 
appropriately with the mouse. The client obtains and sets the value of items by calling 
appropriate Form Window procedures. 

A boolean item is an item with two states (on and off, or TRUE and FALSE). A boolean 
item's value is of type boolean. 

A choice item has an enumerated list of choices, only one of which can be selected at any 
point in time. A choice item's value is of type Formwindow.Cholcelndex. 

A muitiplechoice item is a choice item that can have an initial value of more than one 
choice selected, but any succeeding values can have only one choice selected. A 
muitiplechoice item's value is of tjrpe long descriptor for array of cardinal. 

A text item is a user-editable text string. It contains nonattributed text only. A text item's 
value is of type xstring.ReaderBody. 

A decimal item is a text item that has a value of type XLReai.Number. 
An integer item is a text item that has a value of type long integer. 

A command item allows a user to invoke a command. When the user clicks over a 
command item, a client procedure is called. 

A tagonly item is an uneditable, nonselectable text string. 

A window item is a window that is a child of the Form Window. It can contain whatever 
the client desires. A window item's value is a window.Handie. A client must provide its own 
TiP.NotifyProc and window display proc for the window item. 
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29.1.1 Creating a Form Window 



A client creates a Form Window by calling Formwindow.Create. Create does not actually 
create a window, but rather it takes an already existing window and turns it into a 
ForaiWindow. Windows are usually created by calling StarWindowSheiLCreateBody. 

The client supplies a fWlaiceitemsProc and optionally a LayoutProc to Pormwindow.Create. 
Create calls these two client procedures, first the MaiceitemsProc, then the LayoutProc. In 
the MaiceitemsProc, the client creates the individual items in the form by calling 
FormWindow procedures that make items (see §29.1.2 and §29.2.2). In the LayoutProc, the 
client specifies where each created Item should be positioned in the window by calling 
FormWindow procedures that specify layout (see the sections labeled Layout in this 
chapter). 



There is a procedure for making each type of item: IVIakeBooieanitem, MakeChoiceltem, 
ly^akeCommandltem, ly/laiceOecimaiitem, l\4akelntegeritem, MalcelVlultipieChoiceitem, 
IVIakeTagOniyltem, IVIaiceTextltem, IVIalceWindowitem. Each item must have a unique 
"key", a FormWindow. ItemKey. This is a cardinal supplied by the client to each 
IWIakeXXXItem call. This key is then used in any future calls to manipulate that item, such 
as to get the value of the item. The key must be unique within the FormWindow. 

All items have some common characteristics and some tjrpe-unique characteristics. The 
common ones are described here. Every item can have a tag that will appear to the left of 
the item and a suffix that will appear to the right of the item. An item can have a box 
drawn around it or not. The default is to draw the box. Items can be read-only, that is the 
user cannot change the value of the item. Items can be visible of invisible, and invisible 
items can. either take up white space in the window or not. See §29.2.2 for more details. 



29.1.3 Getting and Setting Values 

Every item that has a value that the user can change (all except tagonly and command 
items) also has procedures for the client to get and set the value. These are: 



29.1.2 Making Form Items 



GetBooieanltemVaiue 
GetChoiceltem Vai ue 
GetDecimalltemVaiue 
GetlntegerltemVaiue 



OoneLoolclngAtTextltemVaiue 



SetBooleanltemVaiue 
SetChoiceitemValue 
SetDecimailtemVaiue 
Setintegeritem Value 



GetlViuitipleChoiceitemVaiue 
GetTextltem Val ue 



SetlVluitipleChoiceitemValue 
SetTextltemVaiue 



GetWindowltemVaiue 
LoooicAtTextltem Vai ue 



Viewpoint Programmer's Manual 



29 



Note: All allocation of storage for values of items is handled by Form Window. The client 
, need not keep copies of item values while the Form Window exists. Obtaining the current 

^""^ value of an item is a simple call to one of the GetXXXItemVaiue procedures. This makes it 

easy to ensure that the internal value of an item is always in sync with the display. (See 
§29.2.3 for more details.) Fine Point: This storage allocation scfaieme is opposite to the one used by XDE's 
FormSW, where the client owns the storage for items. 

29.1.4 "Changed** BOOLEAN 

Every item that has a value that the user can change (ail except tagoniy, command, and 
window items) has a ''changed" boolean associated with it. All items are created with this 
boolean set to false. Form Window automatically sets this boolean to true whenever the 
user changes the item. This allows the client to determine which items have changed 
when, for example, the user selects "Done" or "Apply" on a property sheet. The client is 
responsible for resetting the changed boolean to false by calling ResetChanged or 
ResetAilChanged after examining the changed boolean with HasBeenChanged or 
HasAnyBeenChanged. See §29.2.1 for more detail. 

Boolean and choice items can have a client-supplied procedure that will be called whenever 
the item's value changes (see BooieanChangeProc and ChoiceChangeProc in §29.2.1 and 
29.2.2. The client may also supply a GlobalChangeProc that will be called whenever any 
item changes (see §29.2.1). 

29.1.5 VisibiHty 

^'im^ Each item is either displayed in the form window or not. If an item is displayed in the form 

window, it is visible. If an item is not currently displayed, it is either invisible or 
InvisibleGhost. If it is invisible, it does not take up any space on the screen, that is any 
items below it move up to take its screen space. If an item is invisibieGhost, the space that 
it would occupy were it visible is white on the screen. An item's visibility can be changed at 
any time by calling SetVisibility (see §29.2.5.) 

29.1.6 Layout 

The exact layout of items in a form window is done by calling various layout procedures 
after creating the items to be laid out. If an item is not explicitly laid out, it will not appear 
in the form window at alL A OefauitLayout procedure is provided that places each created 
item on a separate line. 

A form window consists of horizontal lines with zero or more items on each line. Each line 
may be a different height. Any desired vertical spacing may be accomplished by using 
appropriate heights for lines. Any desired horizontal spacing may be accomplished by 
using appropriate margins between items. Items may be lined up horizontally by using 
TabStops. Lines are created by calling AppendLine or InsertLine. Items are placed on a line 
by calling Appendltem or Insertltem. (See §29.2.6 for more detail.) 

29.1.7 Neutral Properties 

"^i^ Any item (except command items) can take on a neutral state, which indicates that the 

item has no value at all. This property makes it possible for a client to indicate to the user 
that the item's value is no longer valid in the current context of the form window, or that 
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the value for this item is obtained from somewhere other then this form window. Items in 
the neutral state appear without any indications of value and have their tag, suffix, and 
value box fields painted over with gray diagonal stripes. Since the item actually has no 
value, client calls to GetXXXltem Value for an item in the neutral state result in an error. 

Items can be placed into (and removed from) a neutral state by calls to SetitemNeutralness. 
A neutral item automatically returns to a normal state when the user selects a value for 
that item, or when the item receives the text input focus (in the case of text, integer, and 
decimal items). (See §29.2.8 for more detail.) 

29.2 Interface Items 



29.2.1 Creating a Form Window, etc. 

Create: proceoure[ 

window: window.Handle, 
makeltemsProc: MakeltemsProc, 
layoutProc: LayoutProc nil, 
windowChangeProc: GlobaiChangeProc 4-°nil, 
minOimsChangeProc: MinOimsChangeProc <-nil, 

zone: UNCOUNTED ZONE 4- NIL, 

dientData: LONG POINTER <- NIL ]; 
Create takes an ordinary window and makes it a form window. 

window is a window created by the client. Windows are usually created by calling 
StarWindowShell.CreateBody. 

makeltems is a client-supplied procedure that is called to make the form items in the 
window, makeltems should call various FormWindow.MakeXXXitem procedures (see 
§29.2.2). Fine Point: makeltems is not called alter Create returns, so makeltems can be a nested procedure. 

layoutProc is a client-supplied procedure that is called to specify the desired position of the 
items in the window. layoutProc is called after makeltems has been called. layoutProc 
should call various layout procedures (see §29.2.6), such as AppendLlne and Appendltem. 
If the default is taken, the OefaultLayout of one item per line will be used. 

windowChangeProc is the global change proc for the entire window. Any time any item in 
the window changes, this procedure is called. 

zone is the zone from which storage for the items will be allocated. Form Window uses a 
private zone if none is supplied. 

clientData is passed to makeltems, layoutProc, and windowChangeProc when called. 
May raise Error[alreadyAForm Window]. 

OefaultLayout: LayoutProc; 

The default for the Create layoutProc parameter. Specifies a layout of one item per line. 
Destroy: procedure (window: window.Handle]; 
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Destroy destroys all Form Window data associated with window, turning it back into an 
ordinary window. All form items are destroyed, but the window itself is not destroyed. May 
raise Error{notAFormWindow]. 

GetClientData: procedure [window: window.Handle] 
RETURNS [clientData: long pointer]; 

GetClientData returns the clientOata that was passed to Create. May raise 
Error[notAFormWindow]. 

GiobalChangeProc: type a procedure [ 
window: window.Handle, 
item: ItemKey, 

cailedBecauseOf : ChangeReason, 
ciientData: long pointer]; 

The client may supply a GiobalChangeProc to Create. Any time the value of any item in the 
window is changed, the GiobalChangeProc is called with the key of the item that was 
changed. If more than one item was changed at one time (such as by a client call to 
Form Window. Restore), nullltemKey will be passed in and the client must examine the 
''changed'* boolean of all items to see what was changed (see §29.2.4). cailedBecauseOf 
indicates what kind of action caused the GiobalChangeProc to be called. ciientOata is the 
LONG POINTER that was passed to Create. 

GetGlobalChangeProc: procedure [window: window.Handle] 
RETURNS [proc: GiobalChangeProc]; 

GetGlobalChangeProc returns the GiobalChangeProc that was passed to Create. May raise 
Error[notAFormWindow]. 

SetGiobalChangeProc: procedure [window: window.Handle, 
proc: GiobalChangeProc] returns [old: GiobalChangeProc]; 

SetGiobalChangeProc changes the GiobalChangeProc that was passed to Create. May raise 
Error[notAFormWindow]. 

MinOimsChangeProc: type a procedure [window: window.Handle, 
old, new: window.Dims]; 

Whenever the minimum dimensions of the FormWindow change, the client supplied 
MinOimsChangeProc is called. This is useful for form windows that are nested as window 
items inside another outer form window. Whenever the dimensions of the nested form 
window change (due to items being made visible or invisible or a text item growing or 
shrinking or new items being added or...), the client that created the window item and the 
nested form window can be called so that it can make the window item bigger or smaller for 
the nested form window to be completely visible. See also NeededDims. 

SetMinOimsChangeProc: procedure [window: window.Handle, 
proc: MinOimsChangeProc] returns [old: MinOimsChangeProc]; 
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SetMinOimsChangeProc changes the MinOimsChangeProc that was passed to Create. May _ 
raise Error [notAFormWindow]. SetMinOimsChangeProc is defined in 
Form WindowExtra2. mesa. 

GetZone: procedure [window: window.Handle] 
RETURNS [zone: uncounted zone]; 

GatZone returns the zone associated with the FormWindow. May raise 
Error[notAFormWindow]. 

isit: procedure [window: window.Handle] returns [yes: boolean]; 

isit is used to determine If a window is a form window. If window was made into a form 
window by calling PormWindow.Create, then Isit returns true, else false. 

LayoutProc:TYPE « procedure [window: window.Handle, ciientData: long pointer]; 

The client supplies a LayoutProc to Create to specify the location of items created by the 
MaiceltemsProc. See §29.2.6 for details of layout. 

MaiceltemsProc: type ■ procedure [ 

window: window.Handle, 
- clientOata: LONG pointer]; 

The client supplies a MaiceltemsProc to Create to make the form items in the window. 
Create will call the client's MaiceltemsProc, and it should call various MakeXXXItem 
procedures (see §29.2.2) to make the items, window should be passed to the various 
MalceXXXItem. clientOata is the same as that passed to Create. Fine point for clients of 
PropertySh«et: dittntOata can be passed to PropertySh«et.Cr«ate and will be passed on to FormWindow.Create 
and the MalceitemsProc. 

NeededOims: procedure [window: window.Handle] 

RETURNS [Window.Oims]; 

NeededOims returns the minimum dimensions required for a window to hold all the 
currently visible items in the form. 

NumberOfltems: procedure (window: window.Handle] returns [cardinal]; 

NumberOf Items returns the current number of form items in window. This count will 
include visible and invisible items. This is useful for clients that create additional items 
dynamically after the form has been created. May raise Error[ notAFormWindow]. 

Repaint: procedure [window: window.Handle]; 

Repaint causes a window.Validate on window. This is used in conjunction with the 
SetXXXItem Value, SetVisibility, Appendltem, and Insertltem procedures. All these 
procedures take a repaint: boolean parameter. To minimize screen flashing while 
changing several items at the same time, the client may call these procedures with repaint 
■ FALSE, then call FormWindow.Repaint. The form window will not be repainted until Repaint illiiii^ 

is called. Warning: After calling any procedure with repaint ■ false, FormWindow.Repaint 
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must be called. Otherwise, the screen will be inconsistent with the internal values. May 
raise Error[notAForm Window]. 

29.2.2 Making Form Items, etc. 

Create procedures are provided for each type of item. These MakeXXXItem routines are 
used to originally create items in a form window as well as to add items to an existing 
window. 

A number of parameters to each MakeXXXItem procedure are identical and are described 
here, rather than with each procedure. If all of the defaults are taken for an item, it will be 
boxed, with no tags and not read-only. All of these may raise Error[notAFormWindow] ; 

window is the form window the item is contained in. It should be the same as the window 
passed to the client's MakeltemsProc. 

my Key is a client-defined key (ItemKey) for the item. The item key uniquely identifies the 
item and should be used- to make calls on other FormWindow procedures, such as 
GetXXXItemValue. Caution: The key must be unique within this form window. 

tag is the text to be displayed before (to the left of) the item on the same line. (To put a tag 
on a separate line, use MakeTagOnlyitem.) 

suffix is the text to be displayed after (to the right of) the item on the same line. 

visibility indicates whether the item should be displayed on the screen. 

boxed indicates whether the item should have a box drawn around it or not. 

readonly a true indicates that the item can not be edited by the user. The item can still be 
changed by calling a SetXXXItemValue procedure. 

ItemKey: type ■ cardinal; 

ItemKey uniquely identifies an item. An ItemKey is supplied by the client whenever an 
item is made (MakeXXXItem) and should be used thereafter to identify the item to 
FormWindow, such as then calling GetXXXItemValue or Set Visibility. 

ItemType: type ■ machine dependent {choice(O), multiplechoice, decimal, integer, boolean, 
text, command, tagonly, window, last(1 5)}; 

There are several t}rpes of items, each of which serves a different purpose and behaves 
differently for the user. All items except tagonly and command have a current value that 
can be obtained (GetXXXItemValue) and set (SetXXXItemValue). 

A choice item has an enumerated list of choices, only one of which can be selected at any 
point in time. A choice item's value is of type Pormwindow.Choicelndex. 

A multiplechoice item is a choice item that can have an initial value of more than one 
choice selected, but any succeeding values can have only one choice selected. A multiple 
choice item's value is of type LONG descriptor for array of cardinal. 

A text item is a user-editable text string, and contains only nonattributed text. A text 
item's value is of type xstring.ReaderBody. 

A decimal item is a text item that has a value of type XLReai.Number. 
An integer item is a text item that has a value of tjrpe long integer. 
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A boolean item is an item with two states (on and off, or TRUE and FALSE). A boolean 
item's value is of type boolean . 

A command item allows a user to invoke a command. When the user clicks over a 
commcuid item, a client procedure is called. 

A tagonly item is an uneditable, nonselectable text string. 

A window item is a window that is a child of the FormWindow and can contain whatever 
the client desires. A window item's value is a window.Handie. A client must provide its own 
TiP.NotifyProc and window display procedure for the window item. 

nullltemKey: ItemKey; 

nullltemKey is used to indicate no item. 

29.2.2.1 Boolean Items 

MakeBooteanitem: procedure [ 
window: Window.Handie. 
myKey: ItemKey, 
tag : xstring.Reader nil, 
suffix: xstring.Reader 4~NiL, 
visibility: Visibility 4- visible, 
boxed: boolean true, 
readonly: BOOLEAN 4-FALSE, 
changeProc: BooleanChangeProc 4-nil, 
label: BooleanitemLabel, 
InitBoolean: boolean 4- true]; 

MakeBooteanitem creates a boolean item. A boolean item value is of type boolean. When 
the value is true, the item is highlighted. When false, it is not highlighted. When the user 
clicks over the label part of a boolean item, the value toggles. 




suffix 



Unhighlighted boolean item, value « FALSE 



changeProc is a client-supplied procedure that will be called whenever the value of the 
item changes. 

label is the string or bitmap that the user points at to toggle the item's value. If label is a 
string, the string is copied. If label is a bitmap, the bits are not copied, so the client must 
ensure that the bitmap pointer is valid for the lifetime of the form window. 

InitBoolean is the initial value of the item. 

May raise Error[notAForm Window, duplicateitemKey]. 

BooleanitemLabel: type ■ record [ 

var: SELEcrtype: BooleanitemLabelTypeFROM 
string ■ > [ string: xstring.ReaderBody], 
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bitmap » > [ bitmap: Bitmap] 
enocase]; 

BooleanltemLabeiType: type ■ {string, bitmap}; 

A BooleanltemLabel is passed to MalceBooieanltem. It is the part of the item that the user 
points at and is or is not highlighted, depending on the value of the item. A label may be 
either a string or a bitmap. (See §29.2.10 on Miscellaneous TYPEs for the definition of 
Bitmap). If label is a string, the string is copied. If label is a bitmap, the bits are not copied, 
so the client must ensure that the bitmap pointer is valid for the lifetime of the form 
window. 

BooleanChangeProc: type ■ procedure [ 
window: window.Handle, 
item: ItemKey, 

cailedBecauseOf : ChangeReason, 
- newVaiue: boolean]; 

The client may provide a BooleanChangeProc to MakeBooleanltem. Whenever the Item's 
value changes (true to false or false to true), this procedure is called, window is the form 
window that the item is in. item is the key of the boolean item to which this 
BooleanChangeProc is attached. cailedBecauseOf indicates what kind of action caused the 
change proc to be called, new Value isr the vew value of the item. The item will already have 
the new value when this procedure is called. 

Caution: If a BooleanChangeProc does a SetXXXItemValue, the client should take extreme 
care to prevent infinite recursion. (See §29.3.1.) 

29.2.2.2 Choice Items 



MakeChoiceitem: procedure! 
window: w!ndow.Handle, 
myKey: ItemKey, 
tag: xstring.Reader 4-nil, 
suffix: xstring. Reader 4-nil. 
visibility: Visibility visible, 
boxed: BOOLEAN 4- true, 
readonly: boolean <- false, 
values: Choiceltems, 
initChoice: Choiceindex, 
fuilyOisplayed: boolean <- true, 
verticaliyOisplayed: boolean 4- false, 
hintsProc: ChoiceHintsProc4~NiL, 
changeProc: ChoiceChangeProc 4-nil, 
outlineOrHighlight: OutlineOrHighlight highlight]; 

MakeChoiceitem creates a choice item. A choice item is an enumerated list of choices, only 
one of which can be selected at any time . The choices can be displayed to the user as either 
strings or bitmaps, or some of each. The current choice is highlighted. When the user clicks 
on a choice, it becomes the current choice and is highlighted. Each choice has a client- 
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deHned Choiceindex associated with it that uniquely identifies that choice. The value of a 
choice item is of type Choiceindex. 

values is the list of all the possible choices. An indication of where to wrap the display 
around to the next line can be made by specifying a wrapindicator variant in the 
appropriate place in the values array. If a choice is a string, the string is copied. If a choice 
is a bitmap, the bits are not copied, so the client must ensure that the bitmap pointer is 
valid for the lifetime of the form window. 

InitCholce is the value of the initial choice. 

fullyOisplayed indicates whether all the choices should be displayed or not. If 
fuilyOlsplayed « true, all the choices are displayed. If fullyOisplayed » false, only the 
current choice is displayed, with the rest of the choices being accessed via a popup menu. 
CauHon: bitmaps cannot appear in popup menus, so fullyOisplayed « false should not be 
used if the choices are bitmaps. 

verticallyOisplayed indicates whether the choices should be displayed vertically or 
horizontally. If fullyOisplayed « false, the value of verticallyOisplayed is ignored. Any 
wraplndicators are skipped over when choices are displayed vertically. 

If hintsProc is supplied, it is called to make a popup hint menu. If the default is taken, the 
form window will make a hint menu with all choices. Note: Since menus can only contain 
strings (not bitmaps), a bitmap choice will appear in the hints menu as a number 
indicating the choice's position. Note: This is not the same as the Choiceindex for that 
choice. 

If changeProc is supplied, it is called whenever the choice changes. 

May raise EiTor(notAFormWindow,duplicateltemKey, invalidChoiceNumber]. 

OutlineOrHighlight: type • {outline, highlight}; 

Normally the selected choice for a choice item is indicated by highlighting the choice. The 
OutlineOrHighlight parameter allows the selected choice to be indicated by outlining the 
choice with a black box. This is intended to support the Shading choice item on, for 
example, the triangle and ellipse property sheets in the VlewPoint editor. 

Choiceltems: TYPE ■ long descriptor for array Choiceindex of Choiceltem; 

Choiceltems is the list of possible choice for a choice item. A Choiceltems array is passed to 
MakeChoiceitem. The choices are displayed in the order they appear in the Choiceltems 

ARRAY. 

Choiceltem: TYPE > record [ 

var: select type: ChoiceltemType from 
string ■ > [ 

choiceNumber: Choiceindex, 

string: xstring.ReaderBody], 
bitmap ■ >[ 

choiceNumber: Choiceindex, 

bitmap: Bitmap], 
wrapindicator « > null]; 

ChoiceltemType: type ■ {string, bitmap, wrapindicator}; 
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Choiceindex: TYPE ■ cardinal [0..37777B]; 

A choice item consists of an array of choices (Choiceitems). Each choice (Choiceltem) 
consists of a unique number that identifies the choice (Choiceindex) and either a string or a 
bitmap to display to the user. In addition, the Choiceitems array can contain a 
wrapindicator wherever the client desires the choices be wrapped around to begin another 
line of choices. A wrapindicator Choiceitem is not a real choice and serves only as 
additional layout information for the FormWindow. If Choiceitem is a string, the string is 
copied. If Choiceitem is a bitmap, the bits are not copied, so the client must ensure that the 
bitmap pointer is valid for the lifetime of the FormWindow. 

The client must construct a Choiceitems array before calling IVIalceChoiceitem. This can be 
simplified If all the choices are strings by using the FormWindowlVlessageParse interface. 
This allows all the choices for a choice item to be stored as a single XMessage with 
embedded syntax indicating individual choice strings and choice numbers. (See 
Form Windo wMessagePar se for more detail. ) 

ChoiceChangeProc: type » procedure [ 
window: window.Handle, 
Item: ItemKey, 

cailedBecauseOf: ChangeReason, 
oidVaiue, newVaiue: Choiceindex]; 

The client may provide a ChoiceChangeProc to MakeChoiceltem. Whenever the choice 
changes, this procedure is called, window is the form window that the item is in. item is 
the key of the choice item to which this ChoiceChangeProc is attached. cailedBecauseOf 
indicates what kind of action caused the change proc to be called, old Value and newValue 
correspond to the choice numbers assigned to the choices in ly/lakeChoiceltem. The item will 
have the new value when this procedure is called. 

Caution: If a ChoiceChangeProc does a SetXXXltem Value, the client should take extreme 
care to prevent infinite recursion. See §29.3.1, Calling ChangeProcs. 

Choicel4intsProc: type ■ procedure [ 
window: window.Handle. 
Item: ItemKey] 
returns [ 

hints: long descriptor for array of Choiceindex, 
freeHints: FreeChoiceHintsProc]; 

FreeChoiceHintsProc: type ■ procedure [ 
window: window.Handle, 
item: ItemKey, 

hints: long descriptor for array of Choiceindex]; 

The client may provide a ChoiceHlntsProc to l\Aal(eChoiceltem. Whenever the user points 
at the mouse menu for a choice item, this procedure is called and the hints returned are 
used to construct a popup menu that is displayed. If the user selects one of the choices from 
the popup menu, that choice becomes the current choice. 

window is the form window that the item is in. 

item is the key of the choice item to which this ChoiceHlntsProc is attached. 
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hints is an array of choice numbers for the choices that the client wants to appear in the 
menu. This allows a client to show a subset of all the choices to the user for situations in j/m^ 
which not all the choices make sense, hints must be allocated by the client. 

freeHints is a procedure that will be called after the hint menu has been taken down to 
allow the client to free any storage that was allocated when creating the hints array. 

MaiceMuitipleChoiceltem: procedure [ 
window: window.Handle, 
myKey: ItemKey, 
tag: xstring.Reader 4- nil, 
suffix: xstring.Reader 4- nil, 
visibility: Visibility «~ visible, 
boxed: boolean 4- true, 
readonly: boolean <~ false, 
values: Choiceltems, 

initChoice: long descriptor for array op Choiceindex, 
vertically Displayed: boolean 4- false, 
hintsProc: ChoiceHintsProc4-NiL, 
changeProc: MultipleChoiceChangeProc 4-nil]; 

May raise Error[notAForniWindow, duplicateitemKey]. 

MultipleChoiceChangeProc: type ■ procedure [ 
window: window.Handle, 
item: ItemKey, 

calledBecauseOf : ChangeReason, 

oidValue: long descriptor for array of Choiceindex, 

newValue: long descriptor for array of Choicelndex]; 

A multiple choice item is identical to a choice item, except that it may have more than one 
initial value. See MakeChoiceltem above for details of choice items. A multiple choice item 
is useful for showing the properties of a heterogenous selection, such as the font property of 
a text selection that has more than one font. 



29.2.2.3 Command Items 



MakeCommandltem: procedure [ 
window: window.Handle, 
myKey: ItemKey, 
tag: xstring.Reader nil, 
suffix: xstring.Reader «-nil, 
visibility: Visibility visible, 
boxed: boolean 4- true, 
readonly: boolean 4~ false, 
commandProc: CommandProc, 
commandName: xstring.Reader, 
clientOata: long pointers- nil]; 



Creates a command item. A command item allows a user to invoke a command. When the 
user clicks over the commandName, commandProc is called. If boxed is true, the 
commandName appears with a rounded corner box drawn around it (rather than a square- 
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cornered box, to distinguish a command item from a boolean item). May raise 
Error(notAFormWindow,dupiicateitemKey]. 

NewMakeCommandltem: procedure [ 
window: window.Handie, 
myKey: ItemKey, 
tag: xstring.Reader 4- nil, 
suffix: xstring.Reader 4-nil, 
visibility: Visibility visible, 
boxed: boolean «- true, 
readonly: boolean false, 
commandProc: CommandProc, 
label: CommandltemLabel, 
clientData: long pointers- nil]; 

CommandltemLabel: TYPE ■ record [ 

var: SELECT type: CommandltemLabelType FROM 
string a > [string: xstring.ReaderBody], 
bitmap ■ > [bitmap: Bitmap], 
endcase]; 

CommandltemLabelType: TYPE a {string, bitmap}) 

NewMakeCommandltem is just like MakeCommandltem, but allows the label to be a 
bitmap. If label is the bitmap variant, the client muist leave the storage for the bitmap 
allocated as long as the item exists. NewMakeCommandltem is defined in 
FormWindowExtra3.mesa. 

CommandProc: type a procedure [ 
window: window.Handie, 
ltem:itemKey, dientOata: long pointer]; 

A CommandProc is supplied by the client to MakeCommandltem. It is called whenever the 
user selects the command item, window is the Form Window that the item is in. Item is the 
key of the command item to which this CommandProc is attached. 

29.2.2.4 Tagoniy items 

MakeTagOnlyltem: procedure [ 
window: window.Handie, 
myKey: ItemKey, 
tag: xstrmg.Reader, 
visibility: Visibility visible]; 

Creates a tagoniy item. Tagoniy items are displayed as uneditable, nonselectable text.May 
raise Error[notAForm Window, duplicateltemKey]. 

29.2.2.5 Text and Number Items 

MakeTextltem: procedure [ 
window: window.Handie, 
myKey: ItemKey, 



29-13 



Form Window 



tag: xstring. Reader *-wl, 
suffix: xstring.Reader 4-NiL, 
visibility: Visibility «- visible, 
boxed: boolean 4- true, 
readonly: boolean 4- false, 
width: CARDINAL, ~ in screen dots 
initString: xstring.Reader 4- nil, 
wrapUnderTag: boolean 4- false, 
passwordFeedback: boolean 4- false, 
hintsProc: TextHintsProc 4-nil, 
nextOutOfProc: NextOutOfProc4-NiL, 
SPEC ALKey board: BiackKays.Key board nil]; 



Creates a text item. Text items are user-editable text strings. The value of a text item is of 
type xstring.ReaderBody. The user may select text, extend the selection, insert text, delete 
text, move and copy text, etc. Text items are fixed width but may grow and shrink 
vertically as the user enters and deletes text. A text item will contain nonattributed text 
only. Form Window handles all storage allocation for the backing string. 

width is the number of screen dots wide that the item should be. The item may grow 
arbitrarily long as the user enters text, but it will always retain the same width. 

initString is the initial string to place in the text item. The bytes are copied by 
FormWindow. 

wrapUnderTag specifies whether any text wider than the width of the text item should 
appear underneath the tag (wrapUnderTag ■ true) or start at the left edge of the text item 
(wrapUnderTag ■ false). Note: This feature is not yet implemented; that is, items always 
behave with wrapUnderTag ■ false. 

passwordFeedback indicates that the text should be displayed in an unreadable form (e.g. 
asterisks) rather than as normal characters. The correct value of the string is maintained 
internally, so that a call to GetTextltemValue will return the proper value. If any part of a 
passwordFeedback field is copied or moved, the underlying string is NOT copied. 

If hintsProc is supplied, it is called to make a list of strings to be displayed to the user as a 
popup hint menu. (See TextHintsProc below.) 

If nextOutOfProc is supplied, it is called when the user presses the NEXT key while the 
input focus is in this text item. This gives the client an opportunity to create more text 
items. After calling the nextOutOfProc or if no nextOutOfProc is supplied, the NEXT key 
causes the selection and input focus to move to the next text or window item in the form. 
See NEXT key in this chapter for further explanation. 

If SPEQALKeyboard is supplied, it allows clients to make a special keyboard available to 
the user when typing into a text or number field. 

May raise Error[notAForm Window, duplicateitemKey]. 

MakeDecimailtem: procedure [ 
window: window.Handle, 
myKey: ItemKey, 
tag : xstring. Reader *- nil, 
suffix: xstring. Reader 4- nil, 
visibility: Visibility <- visible, 
boxed: boolean 4- true. 
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readonly: boolean 4- false, 
signed: BOOLEAN 4-FALSE, 
width: CARDINAL, " in screen dots ~ 
initDecimai: XLReai.Number4-XLReai.zer0, 
wrapUnderTag: boolean <- false, 
hintsProc: TextHintsProc4-NiL, 
nextOutOfProc: NextOutOfProc4-Nit, 
display Template: xstring.Reader 4-nil, 
SPEC ALKey board: Biad(Keys.Key board <-nil]; 

Creates a decimal item. A decimal item is a text item that has a value of type 
XLReai.Number. (See MakeTextltem above for details of text items.) The user can type any 
text into the decimal item, but when the client calls GetDedmalltemValue to retrieve the 
value, FormWindow converts the string to XLReai.Number. InitDecimai is the initial 
decimal value to place in the item. displayTemplate parameter is defined as in the 
XLReai.PictureReal. XLReai.PictureReai is used to display the value of the decimal item. The 
client may provide a keyboard interpretation with the SPEGALKeyboard parameter (see 
BlackKeys chapter ). May raise Error[notAForm Window, dupiicateitemKeyj. 

Makeintegeritem: procedure [ 
window: window.Handle, 
my Key: ItemKey, 
tag: xstring.Reader 4-nil, 
suffix: xstring.Reader 4~ NIL, 
visibility: Visibility visible, 

boxed: BOOLEAN 4- TRUE, 

readonly: boolean false, 
signed: boolean 4- false, 
width: CARDINAL, — in screen dots — 
initlnteger: long integer 0, 
wrapUnderTag: boolean 4~FALSE, 
hi ntsProc: TextH i ntsProc <- nil, 
nextOutOfProc: NextOutOfProc nil, 
SPEQ ALKey board: Bia€kKeys.Keyboard <-nil]; 

Creates an integer item. An integer item is a text item that has a value of type long 
INTEGER. (See MakeTextltem above for details of text items.) The user can type any text into 
the integer item, but when the client calls Getlntegerltem Value to retrieve the value, 
FormWindow converts the string to a LONG integer, initlnteger is the initial number to 
place in the item. The client may provide a keyboard interpretation with the 
SPECIALKeyboard parameter (see BlackKeys chapter). May raise Error[ 
notAForm Window, dupllcateltemKey]. 

TextHlntAction: TYPE ■ {replace, append, nil}; 

TextHintsProc: type > procedure [ 
window: window.Handle, 
item: ItemKey] 
returns [ 

hints: long descriptor for array of xstring.ReaderBody, 
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freeHints: FreeTextHintsProc, 
hintAction: TextHintAction 4- replace]; 

FreeTextHintsProc: type ■ procedure [ 
window: window.Handle, 
item: itemKey, 

hints: long descriptor for array of xstring.ReaderBody]; 

The client may provide a TextHintsProc to MakeTextltem, IMaiceOeclmailtem, and 
Maiceintegerltem. Whenever the user points at the mouse menu for a text item, this 
procedure is called and the hints returned are used to construct a popup menu that is 
displayed. 

When the user selects one of the strings from the popup menu, one of three things will 
happen, depending on the hintAction returned by the TextHintsProc. If hintAction ■ 
replace, the selected string will replace the current value of the text item. If hintAction ■ 
append, the selected string will be appended to the current value of the text item. If 
hintAction « nil, the current value of the text item will not change. hintAction « nil is 
useful for displaying "help-like" information to the user for text items that do not have a 
finite number of possible values, such as a file name. 

freeHints is a procedure that will be called after the hint menu has been taken down to 
allow the client to free any storage that was allocated when creating the hints array. 

29.2.2.6 Window Items 

MakeWindowltem: procedure! f^^. 
window: window.Handle, 
myKey: ItemKey, 
tag: xstring.Reader 4-nil, 
visibility: Visibility 4~ visible, 
boxed: boolean «- true, 
size: window.Dims, 
nextlntoProc: NextlntoProc^-NiL] 
returns [cllentWindow: window.Handle]; 

Creates a window item. A window item is a window (window.Handle) that is a child of the 
FormWindow and can contain anything the client desires. A window with dimensions size 
is created and returned as ciientWindow. It is expected that the client will associate a 
display proc (see window.SetDisplayProc) and a tip. Notify Proc with the window. The window 
may be treated just like any other window, except FormWindow.SetWindowltemSize must be 
used to change the size of the window rather than calling window.SlideAndSize directly. 
This allows FormWindow to move any other items, if necessary, to accomodate the 
different-sized window item. 

If nextlntoProc is supplied, it is called when the user presses the NEXT key in an item just 
before this window item. This gives the window item an opportunity to gain control of the 
NEXT key by setting the input focus to be the window item's window. The window item may 
then retain control of the NEXT key within the window item. When the window item no 
longer wants to process the NEXT key (for instance, when the NEXT key should move the 
selection outside the window item), the window item client must call f^""!^ 
Formwindow.TakeNEXTKey, which returns the NEXT key processing to the form window. (See 
§29.2.10 for an explanation of the NEXT key.) 
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May raise Error[notAFormWmdOw, dupiicateltemKey]. 

SetWindowitemSize: procedure [ 
window: window.Handle, 
windowltemKey: ItemKey, 
newSize: window.Dims]; 

SetWindowitemSizeExtra: procedure [ 
window: window.Handle, 
windowltemKey: ItemKey, 
newSize: window.Oims, 
repaint: boolean 4- true]; 

SetWindowltemSize (or SetWindowitemSizeExtra) should be used to change the size of a 
window item's window. The client should never call window.SlideAndSize directly. Any 
items below the window item are moved down or up to accommodate the new dimensions, 
window is the form window that the window item is in. windowltemKey must be. the key 
of a window item. newSize indicates the new dimensions. SetWindowitemSizeExtra is 
defined in Form WindowExtra. mesa. May raise Error[ notAForm Window, invaiidltemKey, 
wrongltemType]. 

29.2.2.7 Destroying Items 

Oestroyltem: procedure [ 
windowiwindow.Handle, 
item: ItemKey, 
repaint: boolean <- true]; 

Destroyltem destroys item. Most clients will not need to use this procedure, since 
Formwindow. Destroy destroys all the items in the FormWindow. May raise 
Error(notAForm Wi ndow, i n val idltem Key] . 

Destroyltems: procedure [ 
window:window.Handle, 
item : long descriptor for array of ItemKey, 
repaint: boolean 4- true]; 

Destroyltems destroys several items at once. Most clients will not need to use this 
procedure, since FormWindow.Destroy destroys all the items in the FormWindow. May raise 
Error(notAFormWindow, invatidltemKey]. 

29.2.3 Getting and Setting Values 

The client may examine or change the value of an item. All GetXXXItem procedures return 
the current value of an item. All SetXXXItem procedures take a given new value and 
change the value internally, as well as updating the screen if necessary. 

In all these procedures, window is the FormWindow the item is in. item uniquely 
identifies the item to get/set the value of. 

Note: There are two ways to get the value of a text item. GetTextltem Value copies the 
bytes of the string so that the storage for the returned value is owned by the client. 
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LookAtTextltemValue simply returns a pointer to the Form Window-owned backing string. 
This value is therefore read-only and must be released when the client is done examining 
it by calling OoneLookingAtTextltemValue. 

All of these may raise Error[notAForm Window, invalidltemKey, wrongltemType]. If the 
item is in a neutral state (see § 29.2.8), these will raise ItemErrorfneutrailtem]. 



29.2^1 Getting Values 

GetBooleanltemVal ue : procedure [ 
window: window.Handle. 
item: ItemKey] 
RETURNS [value: boolean]; 

GetChoiceltemValue: procedure [ 
window:window.Handle, 
item: ItemKey] 
RETURNS [value: Choicelndex]; 

GetOecimalltemValue: procedure [ 
window: window.Handle, 
item: ItemKey] 

RETURNS [value:xLReai.Number]; 

May raise XLR«ai.Error [notANumber]. 

GetlntegerltemValue: procedure [ 
window: window.Handle, 
item: ItemKey] 
RETURNS [value: long integer]; 

May raise xstring.lnvaiidNumber or XString.Overf low. 

GetMultipleChoiceltemValue: procedure [ 
window:window.Handle, 
item: ItemKey, zone: uncounted zone] 
RETURNS [values: long descriptor for array of Choicelndex]; 



The zone parameter is added. The storage for the descriptor will be allocated out of zone 
and the storage must be freed by the client. 

GetTextltemValue: procedure [ 
window: window.Handle, 
item: ItemKey, 
zone: uncounted zone] 
RETURNS [value: xstring.ReaderBody]; 

GetTextltemValue copies the string. Storage for the bytes is allocated out of zone. The 
client should free the storage using xstring.FreeReaderBytes and zone. 

GetWindowltemValue: procedure [ 
window: window.Handle. 
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item: item Key] 

RETURNS [value: window.Handle]; 

LookAtTextltemValue: procedure [ 
window: window.Handle, 
item: ItemKey] 

returns [value: xstring.ReaderBody]; 

DoneLookingAtTextltemValue: procedure [ 
window: window.Handle, 
item: ItemKey]; 

LookAtTextltemValue does not copy the string but returns a pointer to it. value siiould not 
be changed by the client. Clients using LookAtTextltemValue must call 
DoneLookingAtTextltemValue when done examining it. During the time between these 
calls, if another client calls LookAtTextltemValue or SetTextltem Value for the same text 
item, the second client's process will WAIT. 

GetNextAvailableKey: procedure [vvindow: window.Handle] 
RETURNS [key: ItemKey]; 

Returns the next available item key: MAX[usedKeys] + 1. 

29.2.3.2 Setting Values 

All the SetXXXItem procedures take a repaint: boolean. If repaint a true and the item is 
currently visible, it will be repainted with the new value. If repaint ■ false, the item will 
not be repainted until Form window. Repaint is called. This allows the client to change the 
values of several items at once without the screen flashing for each item. Warning: After 
calling any procedure with repaint ■ false, FormWindow.Repaint must be called. Otherwise, 
the screen will be inconsistent with the internal values. 

Caution: If a change proc does a SetXXXItem Value, the client should take extreme care to 
prevent infinite recursion. (See §29.3.1.) 

SetBooleanltemValue: procedure [ 
window: window.Handle, 
item: ItemKey, 
newVaiue: boolean, 
repaint: boolean 4-true]; 

SetChoiceitemVaiue: procedure [ 
window: window.Handle, 
item: ItemKey, 
newValue: Choicelndex, 
repaint: boolean 4-true]; 

May raise FormWindow.Error[invalidChoiceNumber]. 

SetOecimalltemVaiue: procedure! 
window: window.Handle, 
item: ItemKey, 
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newVaiue: XLReai.Number, 
repaint: boolean <-»true]; 

SetintegerltemValue: procedure [ 
window: window.Handie, 
item: ItemKey, 
newValue: long integer, 
repaint: boolean 4-true]; 

SetMuitipieChoiceltemValue: procedure [ 
windowiwfndow.Handle, 
item: Item Key, 

newValue: long descriptor for array op Choicelndex, 
repaint: boolean 4-true]; 

May raise FormWindow.ErrorfinvalidChoiceNumber]. 

SetTextltemValue: procedure [ 
window: window.Handle, 
item: Item Key, 
newValue: xstring.Reader, 
repaint: boolean 4-true]; 

29^.4 "Clianged** BOOLEAN 

Every item that has a value that the user can change (ail except tagpnly and command 
items) has a "changed" boolean associated with it. All items are created with this boolean 
set to false. FormWindow automatically sets this boolean to true whenever the user 
changes the item or when a client calls one of the SetXXXItem Value procedures. This 
allows the client to determine which items have changed when, for example, the user 
selects "Done" or "Apply" on a property sheet. The client is responsible for resetting the 
changed boolean to false by calling ResetChanged or ResetAllChanged after examining the 
changed boolean with HasBeenChanged or HasAnyBeenChanged. 

HasAnyBeenChanged: procedure [ 
window: Window.Handle] 
RETURNS [yes: boolean]; 

HasAnyBeenChanged returns true if any item's changed boolean is true. May raise 
Error[notAFormWindow]. 

HasBeenChanged: procedure [ 
window: Window.Handle, 
item: Item Key] 
RETURNS [yes: boolean]; 

HasBeenChanged returns true if the user has changed item. The client may reset the 
changed boolean to false by using ResetChanged or ResetAllChanged. If item is tagonly or 
command, HasBeenChanged returns false. May raise Error[notAForm Window, 
invaliditemKey]. 
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ResetChanged: procedure [window: window.Handle, item: ItemKey]; 

ResetChanged sets the changed boolean of item to false. May raise Error[ 
notAFormWindow, invalidltemKey]. 

ResetAllChanged: procedure [window: window.Handle]; 

ResetAllChanged sets the changed boolean of all items to false. May raise Error[ 
notAFormWindow]. 

SetChanged: procedure [ 
window: window.Handle, 
item: ItemKey); 

SetChanged sets the changed boolean of item to true. May raise Error[ notAFormWindow, 
invalidltemKey]. 

SetAllChanged: procedure [ 
window: window.Handle]; 

SetAllChanged sets the changed boolean of all items to true. May raise Error [ 
notAFormWindow]. 

29.2.5 VisibiHty 

Visibility: TYPE a {visible, invisible, invisibleGhost}; 

An item either is or is not displayed in the form window. If an item is displayed in the form 
window, it is visible. If an item is not currently displayed, it is either invisible or 
invisibleGhost. If it is invisible, it does not take up any space on the screen; any items below 
it move up to take its screen space. If an item is invisibleGhost, the space that it would 
occupy were it visible is white on the screen. An item's visibility can be changed anytime 
by calling SetVisibility. 

GetVisibility: procedure [ 
window: window.Handle, 
item: ItemKey] 
RETURNS [visibility: Visibility]; 

GetVisibility returns the current visibility of item. May raise Error[notAForm Window, 
invalidltemKey]. 

SetVisibility: procedure [ 
window: window.Handle, 
item: ItemKey, 
visibility: Visibility, 
repaint: BOOLEAN 4--TRUE]; 

SetVisibility sets the visibility of item. If repaint ■ true and the item's visibility is 
changing, the form window will be repainted. If repaint ■ false, the form window will not 
be repainted until FormWindow.Repaint is called. This allows the client to change the 
visibility of several items at once without the screen flashing for each item. Warning: 
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After calling SetVisibility with repaint ■ false, FormWindow.Repaint must be called. 
Otherwise, the screen will be inconsistent with internal values. May raise 
ErrorCnotAFormWi ndow, i nvalidltemKey]. 

29.2.6 Layout 

The exact layout of items in a form window is done by calling various procedures specified 
below, after creating the items to be laid out. If an item is not explicitly laid out, it will not 
appear in the form window at all. Note that FormWindow.OefaultLayout may be used when 
the client is not concerned with the exact placement of items, but wants a functional form 
window. 

There are two different types of layout. The most common is flexible layout, which allows 
text, decimal, integer, and window items to grow and shrink (and all other items are mov'ed 
around accordingly) as the user or client changes their values. Flexible layout is done by 
calling such procedures as AppendLine and Appendltem. The other is fixed layout, which 
allows the client to specify exactly where items will go by calling SetltemBox, but does not 
allow text, decimal, integer, and window items to grow or shrink. All items stay where they 
are laid out unless the client calls SetltemBox again. 

29.2.6.1 Flexible Layout 

A form window with flexible layout consists of horizontal lines with zero or more items on 
each line. Lines now are always just tall enough to hold the items on that line. The 
spaceAboveLine parameter specifies the amount of white spae to leave above each line. 
Any desired horizontal spacing may be accomplished by using appropriate margins 
between items. Items may be lined up horizontally by using TabStops (see §29.2.6.2 below). 

Lines are created by calling AppendLine or InsertLine. Items are placed on a line by calling 
Appendltem or Insertltem. The Append routines are used to add items after the previously 
created line or item. The Insert routines are used to add items between previously created 
items or lines. 

AppendLine: procedure [ 
window: window.Handle, 
spaceAboveLine: cardinal «-0] 
RETURNS [line: Line]; 

AppendLine creates a new line and appends it to the bottom of the form window. All items 
must be placed on a line, so AppendLine must be called before any calls to Appendltem. 
The line returned by AppendLine should be passed to Appendltem or Insertltem. window 
is the FormWindow the line is being appended to. May raise Error[notAFormWindow]. 

Line: type; 

Line uniquely identifies a line and is returned by AppendLine and InsertLine. A Line must 
be passed to Appendltem and Insertltem. 

Appendltem: procedure! 0^ 
window: wtndow.Handle, 
item: Item Key, 
line: Line, 
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preMargin: cardinal «~0, 
tabStop: cardinal ^-nextTabStop, 
repaint: boolean 4-true]; 

Appendltem appends item to line. 

preMargin is the number of pixels of white space to place before the left edge of this item. If 
tabs have been set, preMargin is added after placing the item at its tab stop. 

tabStop is the ordinal number of the tab stop at which to place this item. If the default is 
taken, the next tab stop on the line after the previous item is used. If no tabs have been 
defined (i.e., SetTabStops has never been called), tabStop is ignored. See §29.2.6.2 for 
more detail on tabs. 

repaint specifies whether the screen should be repainted after the Appendltem is done. 
When called from the client's LayoutProc, repaint is ignored and the items are not painted 
until the LayoutProc returns. When not called from the client's LayoutProc, and repaint = 
TRUE, the form window will be repainted immediately after appending the item. When not 
called from the client's LayoutProc, and repaint — false, the form window will not be 
repainted until FormWindow.Repaint is called. This allows the client to add several items at 
once without the screen flashing for each new item. Warning: After calling Appendltem 
with repaint = false, FormWindow.Repaint must be called. Otherwise, the screen will be 
inconsistent with internal values. 

May raise Error(notAForm Window, invalidltemKey, noSuchLine]. 

InsertLine: procedure [ 
window: window.Handle, 
before: Line, 

spaceAboveLine: cardinal 4-0] 
returns [line: Line]; 

InsertLine inserts a new line before (above) an existing line. The spaceAboveLine 
parameter indicates how much space (in screen dots) to leave between the previous line 
and this line. This allows clients to leave white space at the top of the form before the first 
line and also provides an easy way to put white space in a form. (See AppendLine for 
details of creating a line.) May raise Error(notAForm Window, noSuchLine]. 

Insertltem: procedure [ 
window: window.Handle, 
item: ItemKey, 
line: Line, 

beforeltem: ItemKey, 
preMargin: cardinal 4- 0, 
tabStop: CARDINAL 4- nextlabStop, 
repaint: boolean <-true]; 

Insertltem inserts item to the left of beforeltem on line. See Appendltem for details of 
placing an item on a line. May raise Error [notAFormWindow, invaiidltemKey, 
noSuchLine, itemNotOnLine]. 

RemoveltemFromLine: procedure [ 
window: window.Handle, 
item: ItemKey, 
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line: Line, 
repaint: boolean 



•true]; 



RemoveitemFromLine will "unlayout" an item that has been previously laid out. This 
allows clients to move an item from one place on the form to another without destroying 
and recreating the item, by calling RemoveitemFromLine followed by a call to Appendltem 
or Insertltem. RemoveitemFromLine will not destroy the item. The item will be "in limbo" 
until it is laid out again using Appendltem or Insertltem. 

LayoutlnfoFromltem: procedure [ 

window: window.Handle, item: ItemKey] 
RETURNS [ line: Line, margin: cardinal, 
tabStop: CARDINAL, box: window. Box]; 

LayoutlnfoFromltem returns various layout characteristics of Item. May raise 
Error[notAForm Window, 1 n vai idltemKey] . 

LineUpBoxes: procedure [window: window.Handie, 
items: long descriptor for array of ItemKey nil]; 

Calling this procedure will force the boxes of the specified items to line up vertically, as in 
most Viewpoint property sheets. If no items are specified, and a Hxed-pitch font is used, the 
first item on every line will line up as shown in Figure 29.1. 



tagi 



boxed boolean item 



tagOnLine2 



boxed choice item 



boxed text item 



very Longlag Line4 



boxed boolean item 



Figure 29. 1 LineUpBoxes 



The specified items must be the first item on their line. The longest tag is measured; then 
the boxed part of each item appears at the next available tab stop after the longest tag. This 
also works for non-boxed items. 



29.2.6.2 Tabs 

TabType: type ■ {fixed, vary}; 

TabStops: type a record [ 

variant: select type: TabType from 
fixed a > [interval: cardinal]. 
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vary a > [list: long descriptor for array of cardinal] 

ENOCASE ]; 

The client may specify tab stops to facilitate lining up items one directly below the other. 
Tabs may be specified two ways: fixed and varying. Fixed tab stops are specified by a single 
CARDINAL (interval) that indicates a tab stop at each interval pixel, such as if interval =: 10, 
there will be tab stops at 10, 20, 30, etc. Varying tab stops are specified by an array of 
CARDINAL, each element of the array indicating the number of pixels from the left edge of the 
window. Typically, a client will call SetTabStops at the beginning of the LayoutProc, then 
call AppendLlne and Appendltem repeatedly, taking the nextTabStop default for each 
item. 

noTabStop: cardinal * cardinal.last-1 ; 

Can be used with Appendltem and Insertltem to indicate that this item should ignore tab 
stops completely. 

defauitTabStops: TabStops • [flxed[lnterval: 100]]; 

SetTabStops: procedure [window: window.Handle, tabStops: TabStops]; 

SetTabStops sets the tab stops for window. Any items laid out before to this call will now 
be moved to conform to these tab stops. May raise Error[ notAForm Wi ndow] . 

nextTabStop: cardinal a . . . ; 

Used for item layout, it is the default for the tabStop parameter for Appendltem and 
Insertltem. Indicates that the next item should be placed at the next tab stop. 

GetTabStops: procedure [window: window.Handle] 
RETURNS [tabStops: TabStops]; 

GetTabStops returns the current tab stops for window. If no tab stops have been set for 
window, tabStops will be fixed with an interval of 0. May raise Error[ notAForm Window]. 

29.2.6.3 Fixed Layout 

SetltemBox: procedure [ 
window: Window.Handle. 
item: ItemKey, 
box: window.Box]; 

SetltemBox is used to set the exact position of an item for fixed layout. With fixed layout, 
all items stay right where they are laid out unless the client calls SetltemBox again. With 
fixed layout, text, decimal, integer, and window items will not grow or shrink. SetltemBox 
is incompatible with flexible layout (such as. AppendLine, Appendltem, SetTabStops, etc). 
Note: Either all layout must be flexible, or all layout must be fixed. Attempting to mix 
them will raise Error[notAForm Window, invalidltemKey]. 
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29.2.7 Save and Restore 

Restore: procedure [window: window.Handle]; 
Save: procedure [window: window.Handie]; 

Restore and Save deal with restoration of a form window to a previous state. Save causes 
the current item values to be saved. Restore causes the previously saved values to be copied 
back Into the form. A Restore done before a Save is a no-op. Save done after Save (but 
before a Restore) overwrites the iirst Save. These procedures support the Reset function of 
property sheets. May raise Error(notAFormWindow]. 

29.2.8 Neutral Properties 

There are times when the client wants to indicate to the user that a particular item no 
longer has a meaningful value. One way of achieving this is to remove the item completely 
from the display by setting its visibility. If the client wishes the item to remain visible, 
however, a different mechanism can be used. All items (except Command items) can be 
placed into a neutral state, indicating that they no longer have a specific value. When an 
item becomes neutral, it's display is changed such that any value indications are removed 
and uniform diagonal- gray stripes are painted over the item's tag, sufHx, and value box. 
Setting an item to or from the neutral state is done by calling SetltemNeutrainess. 

Items will return to a normal state whenever the user selects a value for that item. In the 
case of text, integer, and decimal items, the item will return to a normal state whenever 
the item receives the text input focus. This can be done either by the user POINTing up 
inside the item value box or by NEXTing into the item. In addition, an item will return to a 
normal state whenever a client calls SetXXXItem Value. 

When a text or number item becomes neutral, it's value is cleared before the gray stripes 
are painted over the value box. For boolean and choice items, the value boxes are 
dehighlighted before the stripes are painted. When boolean and choice items are returned 
to a normal state, the values they had prior to changing to neutral are restored. Text and 
number items, however, lose their previous values and are returned to a normal state with 
their values fields empty. 

When an item is in the neutral state, it actually has no value at all. Because of this, calling 
GetXXXltem Value for a neutral item will raise ltemError[neutrailtem]. In addition, since 
the neutral state is not defined for command items, calling SetltemNeutrainess for a 
command item will raise Error[wrongitemType]. 

SetltemNeutrainess: procedure [ 
window: window.Handle, 
item: itemKey. 
neutral: boolean, 
repaint: boolean <~ true]; 

The neutral parameter is used to indicate whether the item should become neutral, or 
return to a normal state and appearance, window is the FormWindow containing the 
item, and item is the specific ItemKey uniquely identifying the item, repaint indicates 
whether the client wishes the display to be updated. If this value is false, the item will not 
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change appearance, but the internal state of the item will be changed. The next time the 
Form Window is repainted, the display will be changed to reflect the current state of the 
item. 

Neutri^lDispiayProc: procedure [ 
window: window.Handler 
box: window.Box 4-window.nullBox]; 

When a window item is set to neutral, only the item's tag and suSRx will be painted with 
gray stripes. Painting the interior of the window is the responsibility of the client. For the 
convenience of clients who wish the item to have a uniform neutral appearance, 
NeutraiOisplayProc will display the neutral gray stripes in box for a given window. If the 
default value for box is used, then stripes will be painted over the entire window. 

IsNeutral: procedure [ 
window: window.Handie, 
item: itemKey] 
RETURNS (yes: boolean]; 

IsNeutral indicates whether a given item is in the neutral state. Will raise 
Error[wrongltemType] if the item is a command item. 

All of the procedures listed in this section and ItemError are defined in 
FormWindowExtraS. 



29.2.9 Item Popup Menus 

SetPopupProc: procedure [ 
window: window.Handle, 
proc: PopupProc] 
RETURNS [ old: PopupProc]; 



PopupProc: type a procedure [ 
window: window.Handle, 
item: Formwindow.ltemKey] 
returns [ menu: MenuOata.MenuHandle 4-niu 
freeProc: MenuFreeProc^NitJ; 

MenuFreeProc: type « procedure ( 
window: window.Handle, 
menuHandle: MenuOata.MenuHandle]; 

A PopupProc provides the client with a mechanism for attaching a popup menu to any item 
in a FormWindovy. If a PopupProc exists for a FormWindow, it will be called whenever the 
user CHORDs over any item in the window. If menu is non NIL, the popup menu described 
by it will be put up. freeProc is a procedure which will be called when the popup menu is 
taken down so that the client can free any storage allocated for the MenuHandle. The 
PopupProc is set for a FormWindow by calling SetPopupProc. If a PopupProc does not 
exists for a FormWindow, the CHORDing action will be ignored. SetPopupProc may raise 
Error[notAFormWindow]. 
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If the PopupProc returns a nil value for menu, the popup menu will not be put up and the j/g^ 
CHORDing action will be ignored. 

The sensitive area for the CHORDing action over an item is the entire area covered by the 
item's tag, suffix, and value box. 

NeutraiPopupProc: PopupProc; 

NeutraiPopupProc is provided for the convenience of those clients that wish to provide a 
popup menu for setting items to a neutral state. The popup menu for this PopupProc 
consists of a single command which will be used to set that item to a neutral state. This 
procedure will return a MenuHandte and MenuFreeProc for text, integer, decimal, boolean, 
choice, and window items. A popup menu is not provided for readOnly, tag, or command 
items. 

All of these types and procedures are defined in FormWindowExtraS. 

29.2.10 Miscellaneous TYPEs 

Bitmap: type « recoro[ 
height, width: cardinal, 
bitsPerLine: cardinal, 
bits: Environment. BitAddress]; 

A Bitmap is the data structure that is passed to MalceBooieanltem and MakeChoiceitem 
for items that are to be displayed as bitmaps, height Is the height in pixels, of the bitmap, 
width is the width in pixels, of the bitmap, bits is a pointer to the actual bits in the bitmap. 
bitsPerUne is the number of bits in each line of bits. bitsPerUne is usually greater than or 
equal to width, and is often a multiple of 16. 

ChangeReason: type » {user, client, restore}; 

A ChangeReason is passed to a GlobaiChangeProc, BooleanChangeProc, and 
ChoiceChangeProc. It indicates whether the change was caused by the user, or by the client 
calling SetXXXItem Val ue, or by the client calling Restore. 

29.2.11 Miscellaneous Item Operations 

GetReadOnly: procedure [window: window.Handle, item: ItemKey] 
returns (readonly: boolean]; 

GetReadOnly returns the current value of the readonly boolean for item. May raise 
Error[notAFormWindow, invalidltemKey]. 

GetTag: procedure [ 

window: window.Handle, 

Item: ItemKey] 

returns [tag: xstring. Reader]; ^^^^^ 

GetTag returns the tag associated with item. May raise Error[notAForm Window, 
InvalidltemKey]. 
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SetSeiection: procedure [ 
• window: window.Handler 
item: ItemKey, 
firstChar: cardinal 
lastChar: cardinal cardinallast] ; 

SetSeiection sets the current selection to be item. This is useful for helping the user correct 
an incorrect user entry, item must be a text, decimal, or integer item. firstChar is the first 
character of the portion of the string to be selected and highlighted. lastChar is the last 
character of the portion of the string to be selected and highlighted. The defaults for 
firstChar and lastChar causes the entire string to be selected. May raise 
ErrorlnotAFormWindow, invalldltemKey, wrongltemType]. 

SetlnputFocus: procedure [ 
window: window.Handle, 
item: ItemKey, 

bef oreChar: cardinal <- cardinallast]; 

SetlnputFocus sets the current input focus to be in item. This is useful for highlighting an 
incorrect user entry, item must be a text, decimal, or integer item. beforeChar is the 
character before which the input focus should go. The default causes the input focus to be at 
the end of the string. May raise Error[notAFormWindow, invalidltemKey, 
wrongltemType]. 

SetReadOnly: procedure [ 
window: window.Handie. 
item: Item Key, 
readonly: boolean] 
RETURNS [old: boolean]; 

SetReadOnly sets the current "readOnly-ness" of item and returns the old value. May raise 
Error[notAFormWindow, invaiidltemKey]. 

SetitemWidth: procedure [window: window.Handle, item: ItemKey, 
width: cardinal]; ' 

This procedure sets the width of an item. Normally, items are as wide as they need to be to 
display the text of the item (except text, decimal, and integer items whose width is 
specified when the items are created). SetitemWidth overrides the normal width of the 
item and thus could result in the text of the item being truncated. SetitemWidth should 
therefore be used with great caution. In particular, programmers should keep in mind that 
applications are intended to be multinational and strings in other languages are often 
longer than their English equivalents. This layout procedure can only be used with a 
flexible layout. 

SetltemFont: procedure [ 
window: window.Handle, 
item: ItemKey, 

newFont: SimpieTextFont.MappedFontHandle «-nil, 
repaint: boolean 4-true]; 
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SetltemFont changes the font of a text or number item. It does not affect the tag or suffix. 
If newFont is nil, the system font is used. May raise ErrorfnotAForm Window, 
invalidltemKey]. SetltemFont is defined in Form WindowExtra4. mesa. 

SetLosingFocusProc: procedure [ 
window: window.Handle, 
item: ItemKey, 
proc: LosingFocusProc]; 

LosingFocusProc: TYPE ■ PROCEDURE[window: Window.Handie, item: ItemKey]; 

SetLosingFocusProc associates proc with item, proc is called whenever item loses the 
input focus, allowing clients to undo things that were done when the input focus was set, 
e.g. clear some SoftKeys. item must be a text or number item. May raise 
Error[notAForm Window, invaiiditemKey]. SetLosingFocusProc and LosingFocusProc are 
defined in Form WindowExtra6. mesa. 

SetTooicFocusProc: procedure [window: window.Handler proc: LosingFocusProc]; 

TookFocusProc: type ■ procedure [window: Window.Handie, item: ItemKey]; 

SetTooicFocusProc associates proc with window, proc is called whenever the form window 
takes the input focus, item is the item that took the input focus, and will be a text or 
number item. May raise Error[notAForm Window, invalidltemKey]. SetTooicFocusProc 
and TookFocusProc are defined in FormWindowExtra6. mesa. 

29.2.12 NEXT Key 

When the user presses the NEXT key while the input focus is in a form window (more 
exactly: in a text, decimal, or integer item in a form window), the form window does the 
following: 

1. If the item with the input focus has a NextOutOfProc,it is called. This gives the client 
an opportunity to, for example, add another blank text item after this one. 

2. Find the next text, decimal, integer, or window item. Note: If the client added another 
text item after the one that had the input focus, that new item will be the one found by 
form window. 

3a. If the next item is a text, decimal, or integer item, the input focus and selection are 
moved to that item. 



3b. If the next item is a window item and the window item has a NextlntoProc, it is called, 
giving the window item an opportunity to take the input focus. For example, if the 
window item contains a table of values, the NEXT key could be used to step from entry 
to entry through the table, but the window item's Tip.NotifyProc would have to do this. 
Note: If a NextlntoProc is supplied for a window item, it MUST call TiP.SetlnputFocus 
so that all further NEXT key notifications will go to the window item. When the window 
item no longer wants the NEXT key (such as the user has NEXTed out of the last entry of 
the table), it must call FormWindow.TakeNEXTKey. TakeNEXTKey proceeds as in steps 2 
and 3. 
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3c. If the next item is a window item, but the window item does not have a NextlntoProc, 
the form window repeats steps 2 and 3. 

NextlntoProc: type » procedure [ 
window: window.Handle, 
item: itemKey]; 

A NextlntoProc can be provided by the client with window items. If provided, the 
NextlntoProc will be called when the user NEXTs into the item using the NEXT key. (See the 
discussion above.) 

NextOutOf Proc: type • procedure [ 
window: window.Handier 
item: ItemKey]; 

A NextOutOf Proc can be provided by the client with text, decimal, and integer items. If 
provided, the NextOutOfProc is called when the user hits the NEXT key while the input 
focus is in an item just before this one. See the discussion above. 

SetNextOutOf Proc: procedure [ 
window: window.Handle, 
item: ItemKey, 

nextOutOfProc: NextOutOfProc] 
returns [old: NextOutOfProc]; 

SetNextOutOfProc sets the NextOutOfProc for a text, decimal, or integer item. This is 
useful when the NextOutOf Proc for a text item creates another text item after itself. After 
creating the new item, the client will probably want to set the NextOutOfProc for the old 
item to NIL, so that next time the user NEXTs out of the old item, the selection and input 
focus will simply move to the new item rather than creating yet another new item, 

GetNextOutOfProc: procedure [ 
window: window.Handle, 
item: ItemKey] 
returns [NextOutOfProc]; 

GetNextOutOfProc returns the NextOutOfProc for item. 

TakeNEXTKey: procedure [ 
window: window.Handle, 
item: ItemKey]; 

TakeNEXTKey informs form window that the window item which was handling the NEXT 
item is done with it and the input focus should be passed on to the next item that can take 
it. item identifies the window item that is involved. May raise Error[notAForm Window, 
wrongltemType]. 

29.2.13 SIGNALS and ERRORs 

Error: error [code: ErrorCode]; 
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ErrorCode: type a machine dependent {notAFormWindow(O), wrongltemType, 
invaiidChoiceNumber, noSuchUner aireadyAForm Window, 
invaiidltemKey, itemNotOnLiner dupiicateitemKey, 
incompatibleLayout, alreadyLaidOut, last(IS)}; 



notAForm Wi ndow 

wrongltemType 

invaiidChoiceNumber 

noSuchLine 
aireadyAFormWindow 

invaliditemKey 
itemNotOnUne 

dupiicateitemKey 
i ncom pati bleLayout 
aireadyLaidOut 



The term notAForm Window means the window passed in to 
the procedure is not a form window. Any Form Window 
procedure, except Create and Isit, may raise this error. 

The term wrongltemType means the item passed in to the 
FormWindow procedure is the wrong type. For example, 
GetChoiceltem Value must be passed a choice item. 

The term InvaiidChoiceNumber means the choice number 
supplied does not match any of the choice numbers in the 
Choiceltems. 

The term noSuchLine means the line supplied to 
Appendltem or Insertltem was not previously created. 

The term aireadyAFormWindow means the window passed 
in is already a form window. Raised if a FormWindow is 
passed into Create. 

The term invaliditemKey means an ItemKey was used for 
which there was no item created. 

The term ItemNotOnLine means an attempt was made to 
insert an item on a line before an item that is not on that 
line. See Insertltem. 

The term dupiicateitemKey means an item was created with 
the key of another item. ItemKeys must be unique. 

The term incompatibleLayout means the client is 
attempting to intermix fixed and flexible layout styles. 

The term aireadyLaidOut means an attempt was made to 
specify the layout for an item more than once. 



LayoutError: signal [code: LayoutErrorCode]; 

LayoutErrorCode: type • {onTopOf Anotherltem, notEnufTabsOefined}; 
The following error and ErrorCode are found in FormWindowExtraS. 
ItemErrcr: error [ errorCode: ErrorCode]; 

ErrorCode: type ■ machine dependent {neutralltem(O), mixedltemjast(1 5)}; 



neutral item 



The term neutralltem means that a call to GetXXXItem Value 
was made on an item in the neutral state. 



mixedltem 



mixedltem presently has no meaning. 
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29.2.14 Multinational items 

Flushness: type » SimpieTextOisplay.FlushneSS; 

StreakSuccession: type ■ siinpi«T«xtoispiay.StreakSuccession; 

GetFiushness: procedure [ 
window: window.Handle, 
item: ItemKey] 
RETURNS [old: Flushness]; 

SetFlushness: procedure [ 
window: window. Handle, 
item: ItemKey, 
new:Fiushness] 
returns [old : Fi ushness] ; 

GetStreakSuccession: procedure [ 
window: window.Handle, 
item: ItemKey] 

RETURNS (old: StreakSuccession]; 

SetStreakSuccession: procedure [ 
window: Window.Handle, 
item: ItemKey, 
new:StreakSuccession] 
RETURNS [old: StreakSuccession]; 

29.3 Usage/Examples 

29.3.1 Calling ChangeProcs 

There are three ways for a client to determine if an item has been changed. (1) The client 
may supply a GlobaiChangeProc that governs the entire window, (2) it may supply a 
XXXChangeProc for certain items (such as choice and boolean), and (3) it may examine the 
'^changed'* boolean associated with each item. 

An item can change because the user changes the item, or because a client calls 
SetXXXltemValue, or because a client calls Restore. 

The two kinds of change procs are called whenever the "changed" boolean goes from false to 
true (whether that is caused by user actions or client actions). The following describes the 
exact order of events for each source of change: 

• User action 

1. Change value of item and set "changed** boolean. 

2. Call local change proc, if any. 

3. Call global change proc, if any. 
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• Client call to SetXXXItemValue 

1. Change value of item and set ''changed" boolean. 

2. Call local change proc, if any. 

3. Call global change proc, if any. 

• Client call to Restore 

1. Change value of item and set "changed" boolean. 

2. Call global change proc, if any, with nullltemKey. 

Note: If a change proc does a SetXXXItem Value, the client should take extreme care to 
prevent inflnite recursion. 

29.3.2 Creating a Simple Form Window 

Myitems: type « {boolean, choice, text}; 



shell: starWindowSh«ii.Handle 4- starwindowSheiLCreate [...]; 
formWindow: window.Handle starWindowSh«ii.Create6ody [shell]; 
Pormwindow.Create [window: formWindow, makeltems: Makeltems, 
layoutProc: OoLayout]; 



Makeltems: FormWindow.MakeltemsProc * { 

< <[y\findow: Window.Handle, cllentData: LONG POINTER] > > 
tag: xstring.ReaderBody; 

" Make a boolean item 

BEGIN 

booieanLabel: Form window.BooleanitemLabel [string! 

xstring.FromSTRING ["This is a boolean item^L]]]; 
tag <~ xstring.FromSTRING ["Tag"Ll; 
FormWindow. MakeBooleanitem [ 

window: window, myKey: IVIyitems.boolean.0RO, 

tag: @tag, label: booieanLabel, 

initBoolean: false]; 
end; 

~ Make a choice item 

BEGIN 

choicel : xstring.ReaderBody 4-xstring.FromSTRING["Choice One"L]; 
choice2: xstring.ReaderBody <-xstring.FromSTRING["Choice 2"L]; 
choices: array [0..2) of Formwindow.Choiceitem [ 

[string[0, choicel 
[string[1,choice21]]; 
tag xstring.FromSTRING ["Choice item"L]; 
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Formwindow.MakeChokeitem [ 

window: window, myKey: Myitems.choice.OROr 

tag: @tag, values: DESCRiPTOR(choices]. 

InitChoice: 0]; 
end; 

~ Make a text item 

tag ^xstring.FromSTRING ["Text item"Ll; 

Formwindow.MakeTextltemC 

window: window, myKey: Myltems.text.ORO, 

tag: @taq, width: 30]; 

}; 

OoLayout: Pormwindow.LayoutProc * { 

< < [window: window.Handle, clientData: LONG POINTER] > > 

Formwindow.SetTabStops [window: window, tabStops: [ fixed [100] ] ]; 

line: FormWindow.Line ^Formwindow.AppendLine [window]; 

— Put boolean and choice item on line 1 

Form Window. Appendltem[window, Myltems.booiean.ORO, line]; 
ForniWindow.Appendltem[window, Myltems.choice.ORD, line]; 

— Put text item on line 2 
line4-Forinwindow.AppendLine [window]; 
FormWindow.Appendltem[window, Myitems.text.ORD, line]; 

}; 

29.3.3 Specifying Bitmaps in Choice Items 

This example creates a choice item with three possible values. Two of them are bitmaps, 
one is a string. The initial value to be highlighted is #2, the string. 

"The bits. (These are in a global frame or a file. They MUST be around for the duration of 
the FormWindow since the bits are NOT copied.) 

bml iFormWindow.Bitmap <-[height:48, width:64, bitsPerLine:64, bits:[@bitmap1[0],0, 0]]; 

bm2:FormWindovtf.Bitmap 4-[height:48, width:64, bitsPerLine:64, bits:[@bitmap2[0],0, 0]]; 

bitmapl : array [0..192) op word [-some bits--]; 

bitmap2: array [0..192) of word [--some bits-]; 

choiceOther: xstring.ReaderBody 4-xstring.FromSTRING["OTHER"]; 

choices: array [0..3) OFFormWindow.Choiceltem [ 

[bitmap(0, bm1] ], 

[bitmap[1, bm2] ], 

[string[2, choiceOther] ] 

]; 

Formwindow.MakeChoiceltem[ 
window: window, 
tag: ©tag, 

myKey: Myitems.choice.ORO, 
values: OESCRiPTORfchoices], 
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changeProc: ChoiceChangeProc, 
initChoice: 2]; 

29.3.4 The NEXT Key and Text Items 

This example creates a text item that inserts a new item after itself every time the user 
presses the NEXT key. 

"Make the text item 

Makeitems: FormWindow.MakeltemsProc « 

3EGIN 



Formwindow.MakeTextiteml 
window: window, 
myKey: Myitems.text.ORD, 
width: SO, 
tag: @tag, 

initString: @initStringLong, 
nextOutOfProc: TextNextOut]; 



end; . 

TextNextOut: Form window. NextOutOfProc ■ 

BEGIN 

tag: xstrinq.ReaderBody <~xstring.FromSTRiNG("lnserted ltem:"L]; 

initString: xstring.ReaderBody 4-xstring.FromSTRING["l DARE you! Edit ME!"L]; 

"Create a new line on which to display the new item 
nextLlne: FarmWindow.Line <- Form window. LayoutlnfoFromltem 

[window, Myltems.testChoice2.0RO].iine; 
line: FormWindow.Line 4-Formwindow.insertLine(window, nextLlne, 60]; 

—create the new item. 
FormWindow.MakeTextltem( 

window: window, 

myKey: cntr, 

"Cntr is a counter to keep track of the next available 

— key number since all ItemKeys are unique 
width: 50, 
tag: @tag, 

initString: ©initString , 
nextOutOfProc: TextNextOut]; 

"put the new item on the line 

FormWindow.Appendltem[ 

window: window, 

item: cntr, 

line: line]; 
cntr «- cntr + 1 ; 
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--set the last item's NextOutOfProc to NIL 

[] 4-Forinwindow.SetNextOutOfProc[window, item, NIL]; 

end; 

29.3.5 Window Items (Including Interaction with the NEXT Key) 

This example creates a window item that wishes to be given control when a user nexts into 
it. 

—create the item 

Makeitemss FormWindow.MakeltemsProc ■ 

BEGIN 

dims: window.Oims [200,200]; 

niy Window Form window.MakeWindowltem( 
window: window, 
myKey: Myttems.window.ORO, 
tag: @tag. 
size: dims, 
destroyProc: nil, 
nextlntoProc: MyNextlnto]; 

"Set the display and notify procs 

Q 4- window.SetDisplayProcfmy Window, WindowltemDispiayProc]; 
n <-TiP.SetTableAndNotifyProc [window: my Window, 
table: TiPStar.NormaiTabieQ, notify: MyNotify]; 

end; 

"MyNextlnto is called when a user presses the NEXTiiey "into" the window item 
MyNextlnto: FormWindow.NextlntoProc ■ 

BEGIN 

—set the input focus so the window item gets all of the notifications 

TiP.SetlnputFocus [w: myWindow, takeslnput: true]; 

end; 

"FormWindow is notified so the window item no longer requires the next key so 
FormWindow can pass it along to the appropriate item 

MyNotify: Tip.NotifyProc • 

BEGIN 

FOR input: TiP.Resuits results, input.next until input ■ nil do 
WITH z: input select from 

atom ■ > SELECT Z.a FROM 

nextDown ■ > 

FormWindow.TakeNEXTKey 

[window: myWindow.GetParent, item: Myltems.window.ORo]; 

enocase; 
enocase; 
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ENDLOOP; 

end; 

29.3.6 Hints 

This example creates a text item that has a popup menu associated with it: 
Makeltems: PormwindoMr.MakelternsProc ■ 

BEGIN 

Pormwindow.MakeTextltemt 
window: window, 
my Key: Myitems.text.OROt 
width: 50, 
tag: Otag, 

initString: @initString, 
hintsProc: TextHintsJ; 

end; 

'•Every time TextHlnts is called, specify the strings to put into the popup menu. The 
hintAction specifies that when a string is selected from the hints menu, it should replace 
the string in the text item 

TextHints: FormWindow.TextHintsProc » 

BEGIN 

hintsArray * — some computation—; 

RETURN (hints: OESCRiPTOR(hintsArrayI,freeHints: FreeHints, hintAction: replace]; 
end; 

FreeHints: Form window. FreeTextHintsProc « 

BEGIN 

"free the strings and whatever other storage here 
end; 

29.3.7 Saving and Restoring Items 

The following example saves the original values of the items in a form window and restores 
them when the user presses RESET. 

'•When creating the FormWindow also call 
Form Window . Save[wi ndow] ; 

'•user changes some values 

••user decides he wants the original values back; presses Reset 
FormWindow.Restore{wlndow]; 
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29.4Index of Interface Items 



Item 


Page 


Item 


Page 


Appendltem: procedure 


22 


HasAnyBeenChanged: procedure 


20 


AppendLine: procedure 


22 


HasBeenChanged: procedure 


20 


Bitmap: type 


26 


Insertltem: procedure 


23 


BooleanChangeProc: type 


8 


InsertUne: procedure 


23 


BoolaanltemLabel: type 


8 


Isit: procedure 


5 


BooieanltemLabeiType: type 


8 


IsNeutral: procedure 


27 


ChangeReason: type 


26 


item:ltemKey 


5 


ChoiceChangeProc: type 


11 


ItemError: error 


29 


ChoiceHintsProc: type 


11 


ItemKey: type 


7 


Choicelndex: type 


10 


ItemType : type 


7 


Choiceitem: type 


10 


LayoutError: signal 


29 


Choiceitems: type 


10 


LayoutErrorCode: type 


29 


ChoiceltemType: type 


10 


LayoutlnfoFromltem: procedure 


24 


CommandltemLabei: type 


13 


LayoutProc: type 


6 


CommandltemLabeiType: type 


13 


Line: type 


22 


CommandProc: type 


13 


Li neU pBoxes : procedure 


24 


Create: procedure 


4 


LookAtTextltemValue: procedure 


18 


DefaultLayout: LayoutProc 


4 


LosingFocusProc: type 


28 


defauitTabStops:TabStops 


25 


MakeBooleanltem: procedure 


8 


Destroy: procedure 


4 


MakeChoiceltem: procedure 


9 


Oestroyitem: procedure 


17 


MakeCommandltem: procedure 


12 


Destroy Items: procedure 


17 


MakeDecimalltem: procedure 


14 


DoneLookingAtTextltem Value: procedure 


19 


Makeintegerltem: procedure 


15 


Error: error 


29 


MakeitemsProc: type 


6 


ErrorCode: type 


29 


MakeMultipleChoiceitem: procedure 


11 


Flushness: type 


30 


MakeTagOnlyitem: procedure 


13 


FreeCholceHintsProc: type 


11 


MakeTextltem: procedure 


13 


FreeTextHlntsProc: type 


15 


MakeWindowitem: procedure 


16 


GetBooleanltemValue: procedure 


18 


MenuFreeProc: type 


27 


GetCholceltemValue: procedure 


18 


MlnOimsChangeProc:TYPE 


5 


GeKlientData: procedure 


4 


MuitipieCnoiceChangeProc: type 


12 


GetDecimalltemValue: procedure 


18 


NeededDims: procedure 


6 


GetFlushness: procedure 


30 


NeutraiDisplayProc: procedure 


27 


GetGlobalChangeProc: procedure 


5 


NeutralPopupProc: procedure 


28 


Getlntegerltem Value: procedure 


18 


NextlntoProc: type 


29 


GetMuitipieChoiceltemVaiue: procedure 


18 


NextOutOfProc: type 


29 


GetNextAvailabieKey:PROCEDURE 


19 


nextTabStop: cardinal 


25 


GetNextOutOfProc: procedure 


29 


NewMakeCommandltem: procedure 


12 


GetReadOnly: procedure 


26 


noTabStop:cAROiNAL 


25 


GetStreakSuccession: procedure 


31 


null Item Key: ItemKey 


7 


GetTabStops: procedure 


25 


NumberOfltems: procedure 


6 


GetTag: procedure 


26 


OutlineOrHighlight:TYPE 


10 


GetTextitemValue: procedure 


18 


PopupProc: type 


27 


Get Visibility: procedure 


21 


Repaint: procedure 


6 


GetWindowltem Value: procedure 


18 


RemoveltemFromLine:PROCEDURE 


23 


GetZone: procedure 


5 


ResetAllChanged: procedure 


21 


GiobalChangeProc: type 


4 


ResetChanged: procedure 


20 
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Item 



Page 



Restore: procedure 26 

Save: procedure 26 

SetAliChanged: procedure 21 

SetBooieanitem Value: procedure 19 

SetChanged: procedure 21 

SetChoiceitem Value: procedure 19 

SetOecimalltemValue: procedure 19 

SetFlushness: procedure 30 

SetGlobalChangeProcs:PROCEDURE 5 

SetlnputFocus: procedure 27 

Setlntegerltem Value: procedure 19 

SetltemBox: procedure 25 

SetltemFont: procedure 27 

SetltenriNeutralness: procedure 26 

SetltemWidth: procedure 27 

SetLosingFocusProciPROCEOURE 28 

SetMinOimsChangeProc: procedure 5 
SetMultipleChoiceitem Value: procedure 20 

SetNextOutOfProc: procedure 29 

SetPopupProc: procedure 27 

SetReadOnly: procedure 27 

SetSelection: procedure 26 

SetStreakSuccession: procedure 31 

SetTabStops: procedure 25 

SetTextltemValue: procedure 20 

SetTookFocusProc: procedure 28 

SetVisibiilty: procedure 21 

SetWindowltemSize: procedure 16 
SetWindowitemSizeExtra: procedure 16 

StreakSuccession: type 30 

TabStops: type 24 

TabType: type 24 

TakeNEXTKey: procedure 29 

TextHintAction: TYPE 15 

TextHlntsProc: type 15 

TookFocusProc: type 28 

Visibility: type 21 
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30.1 Overview 



The FormWindowMessageParse interface provides procedures that parse strings to 
produce various Form Window typcs. These strings are usually acquired from a message 
file. Currently, only Pormuvindow.Choiceltems are supported. 

30.2 Interface Items 

ParseChoiceitemMessage: procedure [ 

choiceitemlVlessage:xstring.Reader, 

zone: uncounted zone] 
RETURNS [choiceltems:Formwindow.Choiceltems]; 

Parses a choiceitemiS/lessage (presumably retrieved using XMessage. Get) with the following 
syntax: "choiceStringichoiceNumberOchoiceStringrchoiceNumber©!", where 
choiceString is the string to be displayed for that choice, choiceNumber is the fixed number 
associated with that choice, @ is the sep€urator between choices, and | indicates the point at 
which to wrap the choices. The choices are displayed in the order they appear in the 
message, choiceitems is a descriptor for an array that must be freed by using 
FreeChoiceitems. 

FreeChoiceltems: procedure [ 

choiceltems:Fonnwvindow.ChoiceltemSr 
zone: uncounted zone]; 

Frees the array and everything it points to (strings). 



30.3 Usage/Examples 

The following example is taken from the folder implementation. The message acquired by 
XM«ssage.Get looks like '*Sorted:0@Unsorted: 1 

choices: FormWindow.Choiceltems 4-FormWindowMessageParM.ParseChoiceltemMessage [ 
XM«ssage.Get[mh, FoiderOps.icpsSorted], z]; 
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Formwindow.MakeChoiceltem [ 
window: window, 
myKey: MyitemType.sorted.ORD, 
values: choices, 
initChoice: sorted.ORD, 
changeProc: SortedChanged ]; 

FonnWindoMrM«ssag«ParM.FreeChoiceitenis(choices, z]; 
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30.4 Index of Interface Items 

Item Page 

FreeChoiceltems: procedure 1 

ParseChoiceltemMessage: procedure 1 
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31.1 Overview 

The idleControl interface provides access to Viewpoint's basic controlling module. 

Viewpoint's control loop is organized as a series of two out-calls to a greeter procedure and 
a desktop procedure. Each procedure is implemented as a procedure variable, initialized to 
an appropriate no-op. 

Interface procedures allow the client to plug in its own greeter and desktop procedures. A 
plugged-in procedure is then called the next time that the control routine goes around the 
loop. 

31.2 Interface Items 

IdleControl keeps track of one GreeterProc and a list of OesktopProcs. A client may plug in 
a number of OesktopProcs and specify the one to be called by the value of the Atom.ATOM 
returned by the GreeterProc. 

31.2.1 DesktopPlug-in 

pesktopProc: type ■ procedure: 

SetDesktopProc: procedure [atom: Atom.ATOM, desktop: DesktopProc] returns [old: 
OesktopProc]; 

SetDesktopProc allows the client to specify the desktop procedure to be called in the 
control loop, desktop is the procedure to be called, atom is the Atom.ATOM associated with 
desktop, old is the previously plugged-in desktop procedure. 

GetDesktopProc: procedure [atom: Atoin.ATOM] returns [OesktopProc]; 

31.2.2 Greeter Plug-in 

GreeterProc: type ■ procedure returns [Atom. ATOM]; 
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SetGreeterProc: procedure [new: GreeterProc] returns [oid: GreeterProc]; 

SetGreeterProc allows the client to specify the greeter procedure to be called in the control 
loop, new is the procedure to be called, old is the previously plugged-in greeter procedure. 

GetGreeterProc: procedure returns [GreeterProc]; 

DoTheGreeterProc: GreeterProc; 

DoTheGreeterProc calls the currently plugged-in GreeterProc. 

31.2.3 Idle Loop 

The control loop is the logical equivalent of : 
00 

atom: Atofn.AT0M 4- pluggedlnGreeterProc []; 
pluggedlnOesktopProc «- GetOesktopProcWithAtom[atom]; 
piuggedinOeslctopProc[]; 
endloop; 

Idle: procedure 

Idle is called or FORKed to enter the idle state. Only clients who start the world should call 
Idle. 

31.3 Usage/Examples 

In the following example, the GreeterProc (IdleProc) displays a bouncing square on the 
screen. The GreeterProc is set in the mainline code of the module. The OesktopProc and 
GreeterProc can be initialized in different modules as long as they agree on the Atom, atom 
(in this case StarOesktop). 

starDesktopAtom: Atom.ATOM <- Atofn.MakeAtoni(*'StarOesktop"L]; 

IdleProc: idi«Controi.GreeterProc ■ begin "Display a bouncing square until the user 
presses any key 

RETURN [starOesktopAtom]; 

end; 

StarOesktop: procedure ■ begin 
•'Do Star logon 

"Initialize and display Star desktop 

"Wait until Logoff 

end; 

I nit: PROCEDURE ■ 
BEGIN 

[] 4-idi«Controi.SetGreeterProc[ldleProc]; 

[] 4-idi«controi.SetDesktopProc [starOesktopAtom, StarOesktop]; 

end; "Oflnit 
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31.4 Index of Interface Items 



Item Page 

OesktopProc: type 1 

OoTheGreeterProc:GreeterProc 2 

DoTheGre6terProc:PROCEOuRE 2 

GetOesktopProc 1 

GetGreeterProc-.PROCEOURE 2 

GreeterProc: type 1 

Idle: PROCEDURE 2 

SetOesktopProc: procedure 1 

SetGreeterProciPROCEDURE 2 
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32.1 Overview 

KeyboardKey is a keyboard registration facility. It provides clients with a means of 
registering "system-wide** keyboards (available all the time, like English, French, 
European), a special keyboard (like Equations), and/or client-specific keyboards (such as 
these available only when the client has the input focus). The labels from these registered 
keyboards are displayed in the soft keys when the user holds down the KEYBOARD key. 

The client adds system keyboards by calling AddToSystemKeyboards. The client registers 
a special keyboard by calling ReglsterClientKeyboards with the SPEClALKeyboard 
parameter. The client registers client-specific keyboards by calling 
ReglsterClientKeyboards with the keyboards parameter. 

32.2 Interface Items 

32.2.1 System Keyboards 

A system keyboard is a one that is available to all clients who wish to recognize some 
general set of keyboards. (The default case is for a client to recognize system keyboards.) 
Examples of system keyboards are the various language keyboards— English, French, 
Europeah,and so forth, and the general-purpose keyboards— Math, Office, Logic, and 
Dvorak. 

AddToSystemKeyboards: procedure (keyboard: BiackK«ys.Keyboardl; 

The AddToSystemKeyboards procedure registers a client's keyboard interpretation with 
the keyboard key manager. The client is expected to provide a pointer to a keyboard record. 
This keyboard is made available whenever system keyboards are available. 

May raise ErrortalreadylnSystemKeyboards]. 

RemoveFromSystemKeyboards: procedure [keyboard: BiadcKeys-Keyboard]; 
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Removes a Keyboard from the list of system keyboards. 
May raise Error(notlnSystemKeyboards]. 

32.2^ Client Keyboards 

A client keyboard is one that is specific to the application and has no meaning in a different 
context. Examples are the special keyboards (such as equations and fields) and 
Spreadsheet and 3270 keyboards. 

A client registers its keyboards with the keyboard manager when it gets control (gets the 
input focus). RegisterCIientKeyboards tells the keyboard manager what keyboards should 
be made available to the user when the KEYBOARD key is held down. When the client loses 
control (releases the input focus) it should call RemoveClientKeyboards to release its 
keyboards. Only 0-1 set of client keyboards is registered at any given time. If no client is 
registered, then all system keyboards are available to the user. 

RegisterCIientKeyboards: procedure [ 
wantSystemKeyboards: boolean «-true, 
SPEQALKeyboard: BiackKeys.Keyboard 4-nil 

keyboards: long descriptor for array of eiackKeys-KeyboardObject 4-nilI: 

RegisterCIientKeyboards establishes a list of client keyboards with the keyboard manager. 
This should occur at the same time the client takes the input focus. wantSystemKeyboards 
specifies whether the client wishes to recognize system keyboards. SPEClALKeyboard 
denotes the keyboard to be invoked by pressing the key combination of KEYBOARD key and 
the soft key labeled "Special". The keyboards array contains any other client keyboards. A 
client typically provides only a Special keyboard and wantSystemKeyboards » true. If 
wantSystemKeyboards a false ,the client should set one of his keyboards using 
SetKeyboard (see section 32.2.3). 

RemoveClientKeyboards: procedure ; 

RemoveClientKeyboards removes the client's keyboards from the keyboard manager's list. 
This list of available keyboards reverts to system keyboards only. The ''Set ** keyboard is 
the last system keyboard that was set (either by the user or a call to SetKeyboard). It is the 
client's responsibility to make sure his keyboards are removed when relinquishing control. 
It is appropriate for this to be done as part of a Tip.LosingFocusProc. 

32.2.3 Setting and Enumerating Keyboards 

Note: Most clients will probably not need to use the information in this section. 
SetKeyboard: procedure [keyboard: BiackKeys-Keyboardl; 

SetKeyboard sets the current keyboard to keyboard. This keyboard remains the current 
keyboard until the user presses a KEYBOARD key/SoftKeyOption/Set combination, which 
chooses a new keyboard, or until another SetKeyboard command is encountered. 

SetKeyboard is provided for those clients who have reason to set a keyboard 
programmatically. The usual case is for the user to set a keyboard by pressing the key 
combination KEYBOARD key/SomeSoftKeyDesignatingAKeyboard. However, for a client 
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calling RegisterClientKeyboards with wantSystemKeyboards » false it is appropriate to 
call SetKeyboard(@oneOfClientKeyboardsl . (Otherwise the user could not type until he 
made a keyboard choice through the KEYBOARD key/SoftKey routine.) The other primary 
reason for calling SetKeyboard is to set an initial keyboard at boot time. 

EnumerateKeyboards: procedure [class: KeyboardClass, enumProc: EnumerateProc]; 

EnumerateProc: TYPE » pROCEOUREtkey board: BiackKeys.Key board, class: KeyboardClass] 

RETURNSlStOp: BOOLEAN 4- FALSE]; 

EnumerateKeyboards calls the specified EnumerateProc until the Stop boolean becomes 
TRUE or until there are no more keyboards to enumerate. When calling 
EnumerateKeyboards, the client may specify which keyboards he wants enumerated: 
system, client, special, or all of the registered keyboards. When the keyboard manager calls 
the client's EnumerateProc, the keyboard returned is qualified by class: client, system, or 
the special keyboard.. 

KeyboardClass: type a {system, client, special, all, none}; 

system > A system keyboard is one that is available to all clients who wish to recognize 
some general set of keyboards. Examples of system keyboards are the various 
language keyboards - English, French, European, etc., and the general-purpose 
keyboards— Math, Office, Logic, and Dvorak. 

client ■ A client keyboard is one that is specific to the application. These are the 
keyboards registered in the keyboards array by the client calling 
RegisterClientKeyboards. 

special ■ A client-specific keyboard is invoked by pressing the combination of KEYBOARD 
key and the soft key labeled "Special". Specifically, this is the keyboard 
registered by the client as SPECI ALKeyboard when calling 
RegisterClientKeyboards. 

ail ■ All keyboeunis: system, client, and special. 



32.2.4 Alternate Keyboard 

SetFirstAltKb: public proc ( 

class: KeyboardKey.KeyboardClass «- client, n XString.Reader 4-nil|; 

Allows clients to establish a first alternate keyboard selection that will be installed when 
the user presses the keyboard key. r is the name of the keyboard 

There are two alternate keyboard possibilities: 

(1) system = > The BasicWorkstation scans the User Profile at each logon for a 
[System] First Alternate Keyboard entry. The system first alternate keyboard will be set 
based on this entry (none if no entry is found). 

Client code can also set the system first alternate keyboard by calling 
SetFirstAltKb[system, reader]. Though this should be done thoughtfully in a way that 
does not interfere with the user or the systems intentions. 
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Since the special keyboard is a special kind of client keyboard that is known to the system, jg!!^ 
calling SetFirstAltKbCspecial] will set the system first alternate keyboard to the special ' ^ 
keyboard. 

(2). client = > The client may set a client first alternate keyboard by calling 
SetFirstAltKbCclient, reader]. Note in the paragraph above that the special keyboard can 
be set as a system first alternate as well as a client first alternate. 

When the user presses the keyboard key If there is a client first alternate keyboard it will 
be installed else if there is a system first alternate keyboard it will be installed. 

When the user releases the keyboard key (assuming no action was taken to change or set a 
keyboard) any alternate keyboard that was installed will be removed leaving the keyboard 
in the same state as it was before the keyboard key was pressed. 

GetFirstAltKb: public proc { 

class: KeyboardKey.KeyboardClass *- client] 
RETURNS (n XStrlng.Reader 4-nil]; 

Returns the name of the first alternate keyboard of class. Any client wishing to 
temporarily set the system first alternate keyboard should first get the current one so that 
it may be reset at the appropriate time. 

32.2.3 Keyboard Window Plug-in 

This section pertains only to those clients interested in implementing a keyboard window 
facility. 

ShowKeyboardProc: type a procedure; 
SetShowKeyboardProc: procedure (ShowKeyboardProci; 
GetShowKeyboardProc: procedure returns [ShowKeyboardProc]; 

SetShowKeyboardProc and GetShowKeyboardProc provide an interface between a 
keyboard window application and KeyboardKey's "Show" key. The clients 
ShowKeyboardProc is called whenever the user presses the key combination KEYBOARD 
key/Show. This gives the client the opportunity to display a keyboard window. 

32.2.6 Errors 

Error: ERROR(code: ErrorCode); 

ErrorCode: type « (alreadylnSystemKeyboards, notlnSystemKeyboards, 
insufficientSpace}: 
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32.3 Usage/Examples 

32.3.1 AddToSystemKeyboards Example 

In this application, a keyboard that will be useful across ail applications has been defined. 
Registering it as a system keyboard will make it available globally. 

usefulKeyboard: BiackK«ys.KeyboardObject 
[charTransiator: (proc: MyCharTrans. data: nil], 
pictureProc: MapPtcture, 
label 4-xstring.FromStringri/se/u/ Keyboard 

KttyboardKey.AddToSystemKeyboards(@myUsefuiKeyboardI; 

The keyboard manager adds the keyboard usefulKeyboard to the list of registered system 
keyboards and a key labeled Useful Keyboard to its labels for the KeyboardKey soft keys. 
When the user pushes the soft key labeled Useful Keyboard, MyCharTrans will be 
registered as the Tip.CharTranslator, and if the keyboard window is open, MapPicture is 
called so that the picture and geometry table can be mapped. 

32.3.2 Special Keyboard Example 

This example contains a keyboard that is specific to a particular application and is 
available to the user through the Special key. The user should also be able to use the 
system keyboards in this application. Notice that it is appropriate to default the label when 
specifying a Special keyboard, because this keyboard is presented to the user as the current 
Special keyboard and is labeled as such. 

AddMyClientKeyboards: procedure » 

BE<3iN 

speciaiKeyboard: BiacfcKeys.KeyboardObject; 

f ileName: xstring.ReaderBody *- xstring.FromSTRiNGCJSpeciai.TIP'L]: 

table: TiP.Table 4-TiP.CreateTabte(@f ileName]: 

D 4-Tip.SetNotifyProcForTabie(table, NotifyProc].- 

speciaiKeyboard 4- (table: table}; 

K«yboardKey.RegisterOientKeyboards[ 

wantSystemKeyboards:TRUE. 

SPEQALKey board: @specialKeyboardl: 
END; - AddMyClientKeyboards 

LosingFocusProc: TiP.LosingFocusProc » 
< <[w: window.Handie, data: long pointer]> > 

BEGIN 

KeyboardKey.RemoveCIientKeyboardsQ; 
"release any data structures I don't want to keep around 
END; ~ LosingFocusProc 
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32.3.3 Registering Multiple Client Keybofiurds Example 

This example deals with a client who has a special keyboard and several client- specific 
keyboards and does not plan to allow the user to use any system keyboards while in this 
application. 

keyboardRecords: array [0..3) of BlackKeys-KeyboardObject: — Records filled in 
speciaiKeyboard: BbckKaysXeyboard: - elsewhere 

AddCIientKeyboards: procedure » 

BEGIN 

KeyboardKey.RegisterClientKeyboardst 

wantSystemKeyboards: false, 

SPEQALKeyboard: speciaiKeyboard. 

keyboards: OESCRiPTOR(keyboardRecordsn; 
K«yboardK«y.SetKeyboard(@keyboardRecords(Oll 
END; - AddCIientKeyboards 

Losing FocusProc; TiP.LosingFocusProc ■ 
< <(w: window.Handle, data: long pointer] > > 

BEGIN 

KeyboardKey.RemoveCiientKeyboardsQ; 
"release any data structures I don't want to keep around 
END; - LosingFocusPro - 
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32.4 Index of Interface Items 



Item 


Page 


AddToSystemKeyboards: procedure 


1 


EnumerateKeyboards: procedure 


3 


EnumerateProc: type 


3 


Error: error 


4 


ErrorCode: type 


4 


G€tFtrstAltKb:PROCEDURE 


3 


GetShowKeyboardProc: procedure 


4 


KeyboardClass: type 


3 


RegisterClientKeyboards: procedure 


2 


Removed ientKey boards: procedure 


2 


RemoveFromSystemKeyboards: procedure 


1 


SetFirstAltKb: procedure 


3 


SetKeyboard: procedure 


2 


SetShowKeyboardProc: procedure 


4 


ShowKeyboardProc: type 


4 
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33.1 Overview 

The BiackKeys and KeyboardKey interfaces provide the framework for including a 
keyboard window in ViewPoint. The window implementation is a plug-in (see 
K«yboardKey.SetShowKeyboardProc). This KeyboardWindow interface and its 
implementation provide one such keyboard window. This KeyboardWindow interface also 
provides a number lock key state. 

33.2 Interface Items 
33.2.1 Default Values 

defaultPicture: BiackKeys-Picture; 
defaultGeometry: BiackK«ys.GeometryTabie: 

The default values provided by this keyboard window implementation correspond to the 
standard English keyboard. 

DefauitPictureProc: BiackKeys-PictureProc: 

OefaultPictureProc returns defaultPicture and defaultGeometry to the caller when 
action a acquire. Clients may specify pictureProc: KeyboardWindow. OefaultPictureProc in 
their BlackK«ys.KeyboardObject if they wish to display the default picture in the keyboard 
window while their keyboard is in effect. 

picture a BiackKeys.nullPicture or BlackKeys.PictureProc » nil will result in the keyboard 
window displaying only gray in the viewing region. 
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33.2.2 Geometry Tabie Structure 

Geometry TableEntry: type » recoro( 
box: Box. key: Keystations, shift: ShiftStatel: 

Box: TYPE M RECORO(place: Window.Place. width: INTEGER, height: INTEGER]; 

Area within the bitmap that generates a particular keystroke when selected with the 
mouse. 

Keystations: type » machine dependent ( 

k1, k2, k3. M, kS, k6, k7, kS. k9. k10, k11, k12, k13, k14, k15, k16, k17, 
k18, k19, k20, k21, k22, k23, k24, k25» k26, k27, k28. k29, k30, k31, k32. 
k33, k34, k35, k36, k37, k38. k39. k40, k41 . k42, k43. k44, k45, k46, k47, 
k48, a1 , a2, a3, a4, aS, a6, a7, a8, a9, alO, a1 1 , a12, tast(96) }; 

The following is a translation to Lev«iiVK«ys.KeyName: 

kl = > One; 
k2 = >Q; 
k3 = > A; 
k4 = > Two; 
k5=>Z; 
k6 = > W; 
k7 = > S; 
k8 = > Three; 
k9 = > X; 



klO 




>E; 


kll 




>D; 


kl2 




> Four; 


kl3 




>C; 


kl4 




> R; 


kl5 




>F; 


kl6 




> Five; 


kl7 




> V; 


kl8 




>T; 


kl9 




>G; 


k20 




> Six; 


k21 




>B; 


k22 




> Y; 


k23 




> H; 


k24 




> Seven; 


k25 




> N; 


k26 




>U; 


k27 




> J; 


k28 




> Eight; 


k29 




> M; 


k30 




>l; 


k31 




>K; 


k32 




> Nine; 


k33 




> Comma; 


k34 




>0; 


k35 




>L; 
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k36 = > Zero; 
J k37 = > Period; 

k38 = > P; 

k39 = > SemiColon; 

k40 = > Minus; 

k41 = > Slash; 

k42 = > LeftBracket; 

k43 = > CloseQuote; 

k44 = > Equal; 

k45 - > RightBracket; 

k46 = > OpenQuote; 

k47 = > Key47; 

k48 = > Tab; " 

al = > ParaTab; 

a2 = > BS; 

a3 s > Lock; 

a4 = > NewPara; 

a6 = > LeftShift; 

a6 = > RightShift; 

a7 = > Space; 

a8 = > A8; 

a9 = > A9; 

alO = > AlO; 

all => All; 

al2 = > A12; 

ShiftState: type * {None. One. Two. Both}; 

Simulates the position of the shift keys associated with the keystroke. 

33.2.3 Bitmap Structure 

Bia€kK«ys.Picture.bitmap is a long pointer. It is further defined within this keyboard window 
implementation as follows: bitmap points to the bits of the keyboard bitmap where dims 
= [505, 1451 and bitmapBitWidth = 32*16. 

33.2.4 Getting to the Keyboard Window Handle 

GetDispiay Window: procedure returns [Window.Handle]: 
Returns handle to the body window of the keyboard window. 

33.2.5 The Number Lock Key State 

NumLockState: TYPE ■ {set. reset}; 
numLockState: NumLockState; 

SetNumLockState: PROCEDURE [newNumLockState: NumLockState]; 
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The number lock key is typically found on the ten key pad. NumLockState indicates the 
states the number lock key can exist, set means the ten key pad is in number mode, reset 
means the ten key pad is in cursor key mode. numLockState is the current state of the 
number lock key. Clients who wish to change the value of numLockState can utilize 
SetNumLockState. 



33^ Usage/Examples 

33.3.1 Using DefauitPictureProc 

OefineKeyboard: procedure • 

BEGIN . 

nameString: xstring.ReaderBody 4-xstring.FromSTRING{''Zuiu''L] 

zuluKeyboardRecord: BiackK«ys.KeyboardObject 4-( 
table: NIL. 

charTransiator: [MakeChar. nil], 

pictureProc: KttyboardWindow.OefaultPictureProc 

label: xstring.CopyToNewReaderBody(@nameString, H«ap.systemZonej]: 
"Save the pointer to the record somewhere for future use — 
END: "OefineKeyboard — 

33.3.2 Using defaultGeometry 

OefineKeyboard: procedure a 

BEGIN 

nameString: xstring.Reader6ody 4-xstring.FromSTRINGrSwahili''L] 

swahiliKeyboardRecord: BiackKeys-KeyboardObject <-[ 
table: NIL. 

charTransiator: [MakeChar, nil], 
pictureProc MapBitmapFile. 

label: xstring.CopyToNewReaderBody(@nameString, H«ap.systemZonei]: 
—Save the pointer to the record somewhere for future use — 
END; —OefineKeyboard — 

MapBitmapFile: BiackKays-PictureProc > 

BEGIN 

pixPtr: BiackK«ys.Picture.bitmap 4-Bia€kKay$.nullPicture: 
SELECT action from 
acquire * > 

(-Oo the right thing to map the bitmap. Uses the default Geometry table 
RETURNfpixPtr. Keyboardwindow.defaultGeometryl }: 
release « > {—Do the right thing to unmap the bitmap 

RETURN(BlackKeys.nullPicture. NIL] } 
END; — MapBitmapFile 
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33.3.3 Sample Geometry Table Entries 

box: [place: [x: XXX, y: XXX], w idth: XXX, height: XXX], key: XXX, shift: XXX 

[[19, 11], 27, 27], k48, None - 'tab' key, dims: whole key picture 

[[51, 11], 27, 14], kl. One - siiifted 'V key, dims: upper half key 

[[51, 24], 27, 14], kl. None - 'V key, dims: lower half key 

[[83, 1 1 ], 27, 14], k4. One - shifted '2' key, dims: upper half key 

[[83, 24], 27, 14], k4. None - '2' key, dims: lower half key 
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33.4 Index of Interface Items 



Item Page 

bitmap structure 3 

Box: TYPE 2 

defauitGeometry: BiackK«ys.Geometry Table 1 

defauitPicture: BiackK«ys.Picture 1 

OefaultPictureProc: BiackK«ys.PictureProc 1 

Geometry TableEntry: type 2 

GetDisplay Window: procedure 3 

numLoci<State: type 3 

NumLocitState 3 

Keystations: type 2 

SetNumLockState: procedure 3 

ShiftState: type 3 
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34.1 Overview 

LeveilVKeys is documented in the Pilot Programmers Manual (610E00160); however, the 
names of several keys were changed for ViewPoint. The key names now more closely match 
the names on the physical keys. 

34.2 Interface Items 

OPEN ks: KeyboardWindow.KeyStations: 
DownUp: TYPE a ks.OownUp; 
Bit; TYPE » ks.Bit; 

KeyBits: type * packed array KeyName of DownUp; 

KeyName: type » machine dependent { 
notAKey(O), 

KeysetKks.KSI). Keyset2(ks.KS2). Keyset3(ks.KS3K Keyset4(ks.KS4). 
KeysetS(ks.KS5), 

MouseLeft(ks.M1), IVIouseRight(ks.M3), MouseMiddle(ks.M2)« 
Five(ks.k16), Four(ks.k12). Six(ks.k20K E(ks.k10), Seven(ks.k24), 
0(ks.k11), U(ks.k26), V(ks.k17h Zero(ks.k36). K(ks.k3lK Minus(ks.k40), 
P(ks.k38), Slash(ks.k41), Font(ks.R8). Same(ks.L8), BS(ks.A2), 
Three(ks.k8), Two(ks.k4), W(ks.k6), Q(ks.k2), S(ks.k7), A(ks.k3), 
Nine(ks.k32), I(ks.k30), X(ks.k9), 0(ks.k34), L(ks.k35), Comma(ks.k33), 
OoseQuote(ks.k43), RightBracket(ks.k45), Open(ks.LII), Keyboard(ks.R11), 
One(ks.k1). Tab(ks.k48), ParaTab(ks.A1), F<ks.k15), Props(ks.L12), 
C(ks.k13). J(ks.k27), B(ks.k21),Z(ks,k5). LeftShift(ks.A5), 
Period(ks.k37), SemiColon(ks.k39), NewPara(ks.A4), 
OpenQuote(ks.k46). Oelete(ks.L3), Next(ks.RI), R(ks.k14). T(ks.k18). 
6(ks.k19). Y(ks.k22), H(ks.k23). Eight(ks.k28), N(ks.k25K M(ks.k29), 
Lock(ks.A3). Space(ks.A7)« LeftBracket(ks.k42), Equal(ks.k44), 
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RightShift(ks.A6). Stop(ks.R12), Move(ks.L9), Undo(ks.R6), Margjns(ks.RS), 
R9(ks.R9), L10(ks.L10K L7(ks.L7), L4(ks.L4K LI(ks.LI), A9(ks.A9h 
R10(ks.R10), A8(ks.A8), Copy(ks.L6), Find(ks.L5), Again(ks.L2), 
Heip(ks.R2), Expand(ks.R7), R4(ks.R4), 02(ks.02), D1(ks.01), 
CenteKks.T2). T1(ks.T1). Bold(ks.T3h ltaiics(ks.T4K Under! ine(ks.T5), 
Superscript(ks.T6), Subscript(ks.T7), Smaller(ks.T8)tT10(ks.T10), 
R3(ks.R3). Key47(ks.k47). A10(ks.A10K befauits(ks.T9K A11(ks.A11), 
A12(ks.A12)}; 
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34.3 Index of Interface Items 

Item Page 

OownUp: Typ« 1 

Bit: Type 1 

KeyBits: Typ«: 1 

KeyName: Type 1 

OPEN ks:KeyboardWindow.KeyStations 1 
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36.1 Overview 

The MenuOata interface defines the data abstraction that is a titled list of named 
commands. It defines the object formats for a menu item and a menu as well as how to 
create and manipulate these objects. It is not concerned with how a menu might be 
displayed to a user. 

35.2 Interface Items 

35.2.1 Menu and Item Creation 

Items and menus are the two primary data objects in the MenuOata interface. Items are a 
name-procedure pair that constitute a command. Menus are an abstraction representing a 
collection of items to be presented to the user. These objects can be built and deallocated 
through this interface. 

Createitem: procedure! 

zone: UNCOUNTED ZONE, 

name:xstring.Reader, 

proc: MenuProc, 

itemOata : long unspecified <- 0] 

RETURNS [ItemHandle]; 

ItemHandie: TYPE ■ long pointer to Item; 

Item: type ■ Privateltem; 

MenuProc: type ■ procedure [ 

window: window.Handle, menu: MenuHandle, itemOata: long unspecified]; 

Createitem builds an item record in the indicated zone to be added to a menu. The name 
parameter is copied so it can be in the client's local frame. The proc parameter is the 
command procedure that is associated with a command name in an item. Client data that 
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must be available when the MenuProc is called can be passed via the itemOata parameter, 
zone can be nil, in which case MenuOata supplies its own zone (see PublicZone below). 

An Item is the representation for a {command- name, command- procedure} pair. The 
**name Width" field, if non-zero, is the display width of the name. It may be set by a module 
that computes the width using Setltem Name Width (see §35.2.3). Except for that, an item is 
read-only. 

Destroyltem: proceourc (zone: uncounted zone, item: ItemHandle]; 

This procedure destroys the item, recovering the space, zone must be the zone in which the 
item was created, and item is the ItemHandle returned by Createltem. The item should not 
be in use when this procedure is called. 

CreateMenu: procedure! 

zone: UNCOUNTED ZONE, 

title: ItemHandle, 
array: ArrayHandte, 

copyitemslntoMenusZone: boolean false ] 
RETURNS [MenuHandle]; 

ArrayHandle: type ■ long descriptor for array of ItemHandle; 

MenuHandle: TYPE » long pointer to MenuObject; 

MenuObject: type ■ PrivateMenu; 

CreateMenu builds a menu record in zone, title is an item containing the menu's title, 
array contains the collection of items that make up the menu. The items pointed to by the 
array and the title parameters are copied only if copyitemslntoMenusZone is true. 
Because item records are read-only, an item can be in several menus without copying. The 
procedure associated with the title item is currently unused and should be nil for future 
compatibility, zone can be nil, in which case MenuOata supplies its own zone (see 
PublicZone below). 

OestroyMenu: procedure [zone: uncounted zone, menu: MenuHandle ] 

OestroyMenu destroys the menu, recovering the space, zone must be the zone in which the 
menu was created; menu is the MenuHandle returned by CreateMenu. It should only be 
called when the menu is not in use. There is no explicit way to test if a menu is in use. 

PublicZone: procedure returns [uncounted zone].- 

PublicZone returns the zone used by MenuOata when Createltem or CreateMenu is called 
with zone a nil. 



35.2.2 Menu Manipulation 



Addltem: procedure [menu: MenuHandle, new: ItemHandle] ■ 
INLINE {menu.swapitemProc [menu: menu, old: nil, new: new]}; 
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Subtractttem: procedure [ menu: MenuHandle. old: ItemHandle] » 
INLINE {menu.swapitemProc [menu: menu, old: old, new: nil]}; 

Swapltem: procedure [ menu: MenuHandle, old, new: ItemHandle] « 
iNUNE {menu.swapltemProc [menu: menu, old: old, new: new]}; 

Tliese procedures alter a menu in the obvious ways. Tliey call through the swapltemProc 
field in the menu object. This allows a module that posts a menu to ''plant" a procedure in 
the swapltemProc field and thus get control on add/subtract/swap requests. With control, 
data can be monitored appropriately. 

SetSwapitemProc: procedure [menu: MenuHandle, new: SwapltemProc] 
RETURNS [old: SwapltemProc]; 

SwapltemProc: type ■ procedure [menu: MenuHandle, old, new: ItemHandle]; 

The SwapltemProc is the work horse for manipulating menus, as evidenced by the inline 
calls above. It can be changed by calling SetSwapitemProc. 

UnpostedSwapltemProc: SwapltemProc; 

This procedure is the standard one that is placed in a menu's swapltemProc when the 
menu is created. It is in the MenuOata implementation, and it can handle altering a menu 
when it is not posted. As discussed above, if a routine that posts a menu wants to get 
control of attempted menu alterations, it should alter the swapltemProc in the menu. 
When it has finished posting the menu, it should store McnuOata.UnpostedSwapltemProc as 
the swapltemProc. Alternatively, it can call McnuOata.UnpostedSwapltemProc from within 
its own swapltemProc to perform the actual alteration of the menu object. 

35.2.3 Accessing Data 

The folloMring provide procedural access to the internal data structures for an item or 
menu. 

ItemData: procedure [item: ItemHandle] returns [long unspecified]; 

ItemName: procedure [item: ItemHandle] 
RETURNS [name: xstring.ReaderBody]; 

SetltemNameWidth: procedure [item: ItemHandle, width: cardinal] « 
INLINE {item.nameWidth <- width}; 

ItemNameWidth: procedure [item: ItemHandle] returns [cardinal] • 
INLINE {RETURN [item.nameWidth]}; 

ItemProc: procedure [item: ItemHandle] returns [proc: MenuProc] « 
INUNE {return [item.proc]}; 

MenuArray: procedure [menu: MenuHandle] returns [array: ArrayHandle] « 
INLINE {return [menu.array]}; 
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MenuTitie: procedure [menu: MenuHandle] returns [title: ItemHandle] « 
INLINE {RETURN [menu.title]}; 

Note: MenuObjects and Items are private records that are of use to menu posters but not of 
interest to general clients. The private records shown below are purely informative. 

Privateltem: TYPE ■ private record [ 
proc: MenuProc, 
nameWidth: natural, 
nameBytes: natural, 
body: select hasltemOata: boolean from 
FALSE a > [nam* xstring.ByteSequenceL 

true ■ > [ItemOata: long unspeofied, name: xstrjng.ByteSequence] 

ENOCASEl; 

PrivateMenu: TYPE • private record [ 
zone: uncounted zone, 
swapltemProc: SwapitemProc, 
title: ItemHandle ^ NIL, 
array: ArrayHandle nil, 
arrayAllocatedltemHandles: natural <-0, 
itemslnMenusZone: boolean 4- false]; 

35.3 Usage/Examples 

A mechanism outside the scope of this interface displays a menu to the user. A given menu 
instance cannot ordinarily be displayed more than once at the same time. 

When the user asks that a command be executed, the command item's procedure is called. 
The window argument is a pointer that is dependent on the display mechanism; it might 
be the starWindowSh«ii.Handle that the menu is posted in. 

35.3.1 Example 1 

sysZ: UNCOUNTED ZONE ■ H«ap.systemZone; 
Init: PROC « { 

sampieTool: xstring.Reader6ody 4-xstring.FromSTRING['*Sample Tooi'*L]; 
Att«ntion.AddMenultem [ 
ManuOata.Createltem [ 

zone: sysZ, 

name: ©sampleTool, 

proc: MenuProc] ] }; 

MenuProc: M«nuOata.MenuProc ■ { 

another: xstring.ReaderBody «-xstring.FromSTRiNG["Another''L]; 
repaint: xstring.ReaderBody xstring.FromSTRtNG[''Repaint"L]; 
post: xstnng.ReaderBody ^-xstring.FromSTRlNGCPost A Message "LJ; 
sampieTool: xstring.ReaderBody 4-xstring.FromSTRING[*'Sample Tool"L]; 

— Create the StarWindowSheU. — 
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shell: starWindowSheii.Handle ■ starWindowSheii.Create [name: @sampleTool]; 



— Create some menu items. — 

z: UNCOUNTED ZONE 4- starwindowSh«ii.GetZone [shell]; 

items: array [0..3) OF MenuOataJtemHandle ( 

M«nuOata.Createltem [zone: z, name: ©another, proc: MenuProc], 
M«nuOata.Createltem [zone: z, name: ©repaint, proc: RepalntMenuProc], 
MenuOata.Createitem [zone: z, name: @post, proc: Post] ]; 

myMenu: MenuOata.MenuHandle • MenuOata.CreateMenu [ 
zone: z, 
title: NIL, 

array: descriptor [items] ]; 
starWindo«wSh«ii.SetRegularCommands [sws: shell, commands: myMenu]; 



}; 

Post: M«nuOata.MenuProc ■ { 

msg: xstring.ReaderBody «-xstring.FromSTRING ["This is a sample attention window 
message.^L]; 

Attention.POSt [@msg] }; 

RepaintMenuProc: MenuOata.MenuProc » { 

body: window.Handle ■ starWindowSh«ii.GetBody[[window]]; 
window.lnvaiidateBox[body, [[0, 0], [30000, 30000] ]]; 
Window. Validate[body] }; 

— Mainline code — 
lnit(]; 

35.3.2 Example 2 

— Declare and create an item title and command array to be placed in a menu — 
mouseMenuTitle: ManuOata.ltemHandle InitMouseMenuTitle []; 
mouseMenuCmnds: array [0..10) OFM«nuOata.ltemHandle; 

— Create the menu - 

mouseMenu: M«nuOata.MenuHandle MenuOata.CreateMenu [ 
zone: MenuData.PublicZone [],-•> could be a client-supplied zone — 
title: mouseMenuTitle, 

array: descriptor [@mouseMenuCmnds[0], 1] ]; 

CommandProc: MenuOata.MenuProc ■ { 

— Does something reasonable for the corresponding item — }; 
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InitMouseMenuTitle: procedure returns [M«nuOata.ltemHandle] • { 
zone: uncounted zone ^ M«nuOata.PublicZone []; 
mouseBitMap: array [0..1 5) of word «- [ ... octal code — ]; 
mouseSymi3olChar: xstrin9.Character <- 

s]mpkiT«xtFofit.AddCIientOeff nedCharacter [ - ... parameters » ]; 
mouseString: xstring.ReaderBody 4-xstring.FromChar [@mouseSymbolChar]; 
cmndTitie: xstring.ReaderBody 4-xstring.FromSTRING ["Command"]; 
mouseMenuCmnds(0] 4-M«nu0ata.Createitem [zone, ©cmndTitie, CommandProc]; 
RETURN [McnuOata.Createltem [zone, ©mouseString, NIL] ] }; 

The above example is just one technique for initializing a menu. The routine 
InitMouseMenuTitle places variables that don't need to be global in the local frame . Pay 
close attention to placement of variables to prevent dangling references. 
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35.4 Index of Interface Items 
Item 



Addltem: procedure 
Array Handle: type 
Createltem: procedure 
CreateMenu: procedure 
Oestroyltem: PROCEDURE 
OestroyMenu: procedure 
Item: type 

itemOata: procedure 
ItemHandle: type 
ItemName: procedure 
ItemNameWidth: procedure 
ItemProc: procedure 
MenuArray: procedure 
MenuHandle: type 
MenuObject: type 
MenuProc: type 
MenuTitle: procedure 
Privateltem: type 
PrivateMenu: type 
PublicZone: procedure 
SetltemNameWidth: procedure 
SetSwapitemProc: procedure 
Subtractltem: procedure 
Swapltem: procedure 
SwapltemProc: type 

UnpostedSwapltemProc: SwapltemProc 



Page 

2 
2 
1 
2 
2 
2 
1 
3 
1 
3 
3 
3 
3 
2 
2 
1 
4 
4 
4 
2 
3 
3 
3 
3 
3 
3 
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38.1 Overview 

Message window provides a facility for posting messages in a window to the user. This is 
similar to posting messages using the Attention Interface, but many message windows can 
be on the screen at once, while there is only one attention window. A message window is 
usually a short window with less than 10 lines of text in it. As more messages are posted, 
previous messages scroll off. 

M«ssag«window. Create takes a '*plain" window, typically obtained by calling 
StarWindowSh«il.CreateBody or FormWindow.MakeWindowltem, and turns it into a message 
window. Messages may then be posted by calling Post. To clear the window, call Clear. 
Various types may be formatted into messages to be posted in the window by using the 
XFormat.Object returned by XFormatObject. 

36.2 Interface Items 

36.2.1 Create, Destroy, etc. 

Create: procedure [window: window.Handle, 

zone: uncounted zone *- nil, lines: cardinal 4-10]; 

Create turns window into a message window, zone will be used for storage of any strings 
posted. If zone is nil, a private zone is used, lines is the number of lines of text to display. 
After more than lines of text are posted, the oldest lines are scrolled out of the window. Fine 
point: The current ViewPoint implementation does not support user scrolling. 

Destroy: procedure [window.Handle]; 

Destroy turns the window back into an ordinary window, destroying any Message Window 
specific context associated with the window. It does not destroy the window. 

Isit: procedure [window.Handle] returns [yes: boolean]; 

Isit returns true if the window was made into a message window by a call to Create. 
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36.2.2 Posting messages 

Post: PROCEDURE [window: window. Handle, 
r: xstrin9.Reader, clear: boolean*- true]; 

Post displays r in window. If clear is true, r starts on a new line. If clear is false, r is 
appended to the last line posted. 

PostSTRING: PROCEDURE [window: window. Handle, 

S: LONG STRiNGr clear: BOOLEAN*- true] a INLINE 
BEGIN 

r: xstring.ReaderBody 4-xstHng.FromSTRIN(3 [s]; 
M«ssageWindow.Post [window, @r, clear]; 
end; 

PostSTRING posts s in window. If clear is true, r starts on a new line. If clear is false, r is 
appended to the last line posted. 

Clear: procedure [window: window.Handle]; 

Clear clears the entire window. 

XFormatObject: procedure [window: window.Handle] returns [o: xFormat-Object]; 

XFormatObject returns an XFormat.Object that can be used to post messages in window. 
The format procedure logically calls Post with clear « false. (See examples.) 

36.3 Usage/Examples 

In the following example, a client displays the name and size of a file. It uses the NSFiie 
interface to access the file and get the name and size attributes. See the Services 
Programmer's Guide (610E00180)--^t/in^ Programmer's Manual for documentation on the 
NSFiie interface. The example intermixes use of the format handle and use of the Post 
procedure. 

msgW: window.Handle 4~FormWindow.MakeWindowitem [. . .]; 
MessageWindow.Create [window: msgW, lines: 5]; 

PostNameAndSize [file, msgW]; 

PostNameAndSize: procedure [file: NSFiie.Handle, msgW: window.Handle ] » { 
nameSeiections: NSFii«.Selections ■ [interpreted: [name: true]]; 
attributes: NSFiioJVttributesRecord; 

msgWFormat: xFarmat.Object 4~Messagewindow.XFormatOb]ect[nisgW]; 
rb: xstring.ReaderBody ^ Message[theFile]; 

M«$sag«window.Post[window: msgW, s: @rb, clear: true]; - start a new message 
xFormat.NSString[@msgWFormat, attributes.name]; /^li 
XFormat.ReaderBody[h: @msgWFormat, rb: Message[contains]]; 
XFormat.Oecimal[h: @msgWFormat, n: NSFii«.GetSizelnBytes(filel]; 
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rb 4- Message{bytes]; 

Me$sag«window.Post(window: msgW, s: @rb]}; - dear defaults to true 

Message: procedure [key: {thePile, contains, bytes}] returns [xstring.ReaderBody] « { 
...}; 

An example of tlie resulting message displayed in the message window is 
The file Foo contains 53324 bytes 
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36.4 Index of Interface Items 



Item Page 

Oear: procedure 2 

Create: procedure 1 

Destroy: procedure 1 

Isit: procedure 1 

Post: procedure 2 

PostSTRI N<j : PROCEDURE 2 

XFormatObject: procedure 2 
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37.1 Overview 

OptionFile reads values from profile files (text files) with the following format: 
[Section] 

Entryl: true — a boolean entry 
Entry2: A string value 
Entry3: 123 ~ an integer entry 

These files are primarily used for keeping user options across logon and boot sessions (thus 
the name profile file). Applications typically read various options out of the current user 
profile file at logon. These options often specify default values for properties, the behavior 
of the application, or both. 

37.2 Interface Items 

37.2.1 Getting Values from a File 

Each GetXXXVaiue procedure takes a section name and an entry name that Identifies the 
entry. It is expected that the section and entry strings are obtained from XMessage. Each 
also takes a file. If file is defaulted, the cxirrent user profile is used (see the Current Profiles 
section below). All these procedures may raise Error [invalidParameters, 
inconsistentVaiue, notFound, syntaxError]. 

GetBooieanValue: procedure [section, entry: xstring.Reader, 
file: NSFito.Reference 4-NSFii«.nuiiReference] 
RETURNS [value: boolean]; 

GetBoolean Value returns the value of a boolean entry. The entry must contain either 
TRUE" or ''FALSE" or the translated string for TRUE or false as defined in the message 
files. 

GetlntegerValue: procedure [section, entry: xstring.Reader, 

index: cardinal 4-0, file: NSFii«.Reference 4-NSFii«.nuiiReference] 
returns [value: long integer]; 
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GetlntegerVaiue returns the value of an integer entry. The entry must contain a number 
that can be parsed by xstring.ReaderToNumber. index causes the indexth entry to be read, 
for repeating entries. 

GetStringVaiue: procedure [section, entry: xstring.Reader, 

callBack: procedure [value: xstring.Reader], index: cardinal <-0, 
file: NSFii«.Reference 4-NSFii«.nullReference]; 

GetStringVaiue calls callBack with the value of a string entry, index causes the indexth 
entry to be read, for repeating entries. 

37.2^ Current Profiles 

Viewpoint supports a current user profile file and a workstation profile file. The current 
user profile is automatically changed whenever a user logs on or ofi!. The workstation 
profile contains entries specific to the workstation rather than specific to each user. There 
is one workstation profile on each workstation. 

GetUserProf ile: procedure returns [file: NSFiic.Reference]; 

GetUserProf lie returns the current User profile file. Note: Each of the Get and Enumerate 
procedures uses this file as the file parameter is defaulted. 

GetWorkstationProfile: procedure returns [file: NSFii«.Reference]; 

GetWorkstationProf ile returns the current workstation profile file. 

Enumerating a File 

EnumerateXXX are useful for applications that look for the same entry in all sections. 

EnumerateSections: procedure [callBack: SectionEnumProc, 
file: NSFii«.Reference 4-NSFii«.nullReference]; 

SectionEnumProc: type ■ procedure [section: xstring.Reader] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

EnumerateSections calls callBack for each section in file, until stop ■ true. If file is 
defaulted, the current user profile is used. 

EnumerateEntries: procedure [section: xstring.Reader, callBack: EntryEnumProc, 
file: NSFito.Reference 4-NSFii«.nullReference]; 

EntryEnumProc: type ■ procedure [entry: xstring.Reader] 

RETURNS [stop: BOOLEAN 4-FALSE]; 

EnumerateEntries calls callBack for each entry in section in file, until stop « true. If file is 
defaulted, the current user profile is used. 
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37.2.4 Errors 

Error: error [code: ErrorCode]; 

ErrofCode: type • {invalidParameters, inconsistentValuer notFound, syntaxError}; 
invalidParameters sucii as passing in a nil string. 

inconsistentValue calling GetBooieanVaiue for an entry that does not have true 

or FALSE as its value, or calling GetlntegerVaiue for an entry 
that will not parse as number. 

notFound asking for an entry that is not in the file. 

invaiidFiie reading from a file that is not a profile file. 

syntaxError garbage in the file. 

NotAProfileFile: signal; 

The passed file is not a profile file; it has the wrong file type. RESUMEing will read the file 
anyway. 

37^ Usage/Examples 

— In globai frame 
displayMessage: boolean true; 

whereToOispiay: SampieBWSAppiicationops.WhereToOisplay <- window; 
messageToOisplay: xstring.Reader <- nil; 

— Called from initialization code 
GetOptionsAtLogon: procedure * { 

logon: Atom.ATOM <- Atom.l\/lakeAtom(''Logon''L]; 
desktopRef : NSFti«.Reference; 

n 4- Ev«ntJVddDependency [agent: LogonEvent, my Data: nil, event: logon]; 

IP (desktopRef 4- siaro«sktop.GeKurrentOe$ktopFiie Q) # NSFii«.null Reference then { 

~ If the desktop is NOT null, then a user's already logged on, 

'•i.e., we got loaded after logon. 

— So we go read the options immediately by calling our 

— Ev«nt.AgentProcedure directly. - 

desktop: NSFiic.Handle NSFii«.OpenByReference [desktopRef]; 

Q 4-> LogonEvent [event: logon, eventOata: loophole [desktop], myOata: NIL]; 

NSFiie.Close [desktop]; 

}; 

}; 

LogonEvent: Event.AgentProcedure • { 

<< [event: Ev«nt.EventType,eventData: long pointer, 
my Data: long pointer] 

RETURNS [remove: boolean false, veto: boolean <- false] > > 

OPEN Ops: SampleBWSApplicationOps; 

mh: XMessag«.Handle ■ 0ps.GetMessageHandle[]; 
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CopyMessageToOispiay: procedure [value: xstring.Reader] > { 
messageToOisplay «-xstring.CopyReader [value, sysZ]}; 

GetWhereToOlspiay: procedure [value: xstring.Reader] ■ { 

window: xstring.ReaderBody 4-xiM«ssag«.Get [mh, Ops.lcwindow]; 
attention: xstring.ReaderBody <-XM«ssag«.Get [mh, Ops.kattention]; 
both: xstring.ReaderBody 4- XMMsag«.Get [mh, opf.kboth]; 
whereToOispiay seucttrue prom 

xstriii9.Eiquivaient [value, ^window] ■ > window, 

xstring.Equivalent [value, ^attention] ■ > attention, 

xstring.Equivalent (value, ©both] ■ > both, 

ENOCASE m > window; 

}; 

section: xstrtng.ReaderBody *~ xMMsag«.Get [mh, Ot».lcAppli€ationNanie]: 

entry: xstring.ReaderBody ^ XM«sMg«.Get [mh, Ops.kOisplay Message]; 
dispiayMessage 4-OpttonFii«.GetBooleanValue [©section, ©entry ! 
OiicionFii«.Error « > continue]; 

entry 4- XM«ssag«.Get [mh, Ops.kMessageToOispiay]; 
OptionFii«.GetStringVaiue [©section, ©entry, GapyMessageToOisplay ! 
optionPito.Error a > continue];. 

entry 4- xM«ssag«.Get [mh, ops.kWhereToDisplay]; 
OptionFii«.GetStringValue [©section, ©entry, GetWhereToOisplay ! 
0|itionFii«.Error ■ > continue]; 

}; 
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37.4 Index of Interface Items 



Item Page 

EntryEnumProc: type 2 

EnumerateEntries: procedure 2 

EnumerateSections: procedure 2 

Error: error 3 

ErrorCode: type 3 

GetBooieanVaiue: procedure 1 

GetlntegerValue: procedure 1 

GetStringValue: procedure 2 

GetUserProfile: procedure 2 

GatWorkstationProfiie: procedure 2 

NotAProfileFile: signal 3 

SectionEnumProc: type 2 
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38.1 Overview 



The PopupMenu interface provides a single procedure that posts a pop-up menu. 

38.2 Interface Items 

Popup: PROCEDURE ( 

menu: M«nuOata.MenuHandle, 
ciients:window.Handle, 
^•"•^ showTitle: boolean true, 

place: window.Place [-1,-11 1; 

This procedure causes the display of the client's menu at or near the indicated place in the 
rootWindow; if the place [-1,-11 is given, the current cursor position is used. If the point 
button goes up while the cursor is over one of the menu items, then that item's 
MenuData.MenuProc is called, clients is passed to the MenuOata.MenuProc as the window 
parameter. The showTitle field indicates whether the menu's title should be displayed 
above its command ^strings. 

The implementation assumes that the point button is down; consequently, the menu is 
displayed until the point button goes up. Popup does not return until the menu is taken 
down» regardless of whether a menu item is selected. 

38.3 Usage/Examples 

Much of the complication in using the PopupMenu interface stems from its reliance on 
MenuOata. A thorough understanding of how to create a menu is needed before using this 
interface (see the MenuOata chapter for details). 

38.3.1 Example 

— Create the menu: 

"^^^ my Menu: MenuOata.MenuHandle MenuOata.CreateMenu [ 
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» Pass in miscellaneous parameters: see the MenuOata interface for details — ]; 
PopupMenu.PopupC 

menu: myMenu* 

clients: currentWindow]; 

- showTitie and place are defaulted in this call. 
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38.4 Index of Interface Items 

Item Page 

Popup: PROCEDURE 1 
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ProductFactoring 



39.1 Overview 

ProductFactoring allows an application to determine whether the customer has purchased 
a particular application. ProductFactoring maintains a record of the applications that have 
been purchased (enabled) on the workstation's disk. Tools are provided to customers for 
enabling various applications (options). The enabling of an application is outside the scope 
of this interface. 

ProductFactoring also allows an application to register a name for its product option, thus 
allowing the product factoring tools to display meaningful names to their users. 

39.2 Interface Items 

39.2.1 Products and ProductOptlons 

Product: type a cardinal [0..16); 

A Product refers to a large set of software. (Also see the ProductFactoringProducts 
interface.) 

ProductOption: type ■ cardinal [0..28); 

A ProductOption refers to a particular piece of software that a customer can buy within a 
Product, such as Spreadsheets, Advanced Star (graphics, or Print Service. To obtain a 
ProductOption for a particular application, see your Xerox Sales Represenative. 

Option: type ■ record [product: Product, productOption: ProductOption]; 

nuilOption: Option ■ . . . ; 

An Option uniquely identifies a ProductOption within a Product. 

39.2.2 Checking for an Enable Option 

Enabled: procedure [option: Option] returns [enabled: boolean]; 
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Enabled returns true if option is enabled on this workstation, otherwise false. Typically, ^iHi^ 
an application calls Enabled every time it is called to perform some user operation such as 
opening an icon. Enabled is fast; it does not read the file every time it is called. It may raise 
Error(notStarted] if there is no product factoring file on the workstation. 



39.2.3 Describing a Product and an Option 



DescribeProduct: procedure [product: Product, desc: xstring.Reader]; 

Provides a name for product, desc is copied to an internal zone. May raise 
Error{illegalProduct] if the value of product is out of range. 

OescribeOption: procedure [option: Option, desc: xstring.Reader, 
prerequisite: Prerequisite nuilPrerequisite]; 

Prerequisite: type « record [ 

prerequisiteSpec: boolean*- false. 
option: Option]; 

nuilPrerequisite: Prerequisite ■ [false, nuilOption]; 

Describes option, desc is a name for the option, prerequisite specifies any other options 
that this option depends on. All data is copied to an internal zone. Use of this procedure 
overrides any earlier definition with the same option value. May raise 
Error[illegalPrdduct] if the value of option. product is out of range. May raise 
Error[illegalOption] if the value of option. productOption is out of range. May raise 
Error[missingProduct] if option.product has not yet been defined. 



39.2.4 Errors 



Error: error [type: ErrorType]; 

ErrorType: type ■ { 

dataNotFound, notStarted, iliegalProduct, iilegalOption, 
missingProduct, missingOption}; 



dataNotFound 

notStarted 

illegalProduct 

iliegalOption 

missingProduct 

missingOption 



The product data file is missing. 

Start proc has not been called yet. 

Not a legal Product value. 

Not a legal ProductOption value. 

The Product specified has not yet been defined. 

The ProductOption specified has not yet been defined. 



39.3 Usage/Examples 



- In global frame ~ 

sampleApplicationPFOption: ProductPactoring.ProductOption ■ 27; 



39-2 



Viewpoint Programmer's Manual 



39 



— 27 was chosen arbitrarily for this sample. — 

— A real application should obtain a real ProductOption/ - 

— Called during initialization — 
InitProductFactoring: procedure * { 

mh: XM«ssag«.Handie « SampleBWSAppncationops.GetMessageHandleQ; 
rb: xstring.ReaderBody <- XM«ssa9«.Get [mh, 

SampieBWSAppiicationops.kApplicationName]; 
Productfactoring.OescribeOption [ 

option: [ product: PrQductFactoringProdiicts.Star, 

productOption: sampleAppiicationPFOption], 
desc: @rb]; 

}; 

— GenericProc - 

GenericProc: Contain««.GenericProc « { 
IF 'ProductFactoring.Enabled (option: [ 

product: ProductPactorjngProducts.Star, 
productOption: sampieApplicationPFOption]] then { 
mh: XM«$sag«.Handie ^SampieBWSAppilcationOps.GetMessageHandle{]; 
rb: xstring.ReaderBody 4-XMessage.Get (mh, SampieBWSAppllcationops.kNotEnabied]; 
ERRORContaifM«.Error [@rb]; 

}; 

select atom from 
}; 
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39.4 Index of Interface Items 

Item Page 

DescribeProduct: procedure 2 

OescnbeOption:PROCEOURE 2 

Enabled: procedure 1 

Error: error 2 

ErrorType: type 2 

nuiiOption: Option 1 

nuilPrerequisite: Prerequisite 2 

Option: type 1 

Prerequisite: type 2 

Product: type 1 

ProductOption: type 1 



ProductFactoringProducts 



40.1 Overview 

ProductFactoringProducts defines the ProductFactoring.Products for various Xerox products. 
(See the ProductFactoring Interface). 

40.2 Interface Items 

Product: type ■ ProductFactoring.Product; 
'•nip^ star: Product • 0; 

Star defines the Xerox Star (aka ViewPoint) workstation product. 
Services: Product ■ 1; 

Services defines the Xerox network services product. 
DFonts: Product » 3; 

OFonts defines the product for Xerox display fonts. 
PFonts: Product ■ 4; 

PFonts defines the product for Xerox printer fonts. 
Viewpoint: Product ■ 5; 

Viewpoint defines a product for Xerox ViewPoint applications. 
ViewPointApps: Product a 6; 

ViewPointApps defines a product for Xerox ViewPoint applications. 
Converter: Product ■ 7; 

Converter defines the product for Xerox ViewPoint converter icon applications. 
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Services2: Product a 8; 

Services2 deHnes another Xerox network services product. It is defined in 
ProductFactoringProductsExtras. mesa. 

Languages: Product ■ 9; 

Languages defines the Xerox languages product. It is defined in 
ProductFactoringProductsExtras2.mesa. 

FujiUnique: Product ■ 10; 

Fuji2Unique: Product ■ 11; 

FujiUnique and Fuji2Unique define Fuji Xerox products. These are defined in 
ProductFactoringProducts£xtras3.mesa. 

OahuUnique: Product « 12; 

OahuUnique defines the Xerox Oahu product. It is defined in 
ProductFactoringProductsExtras4. mesa. 

RankUnique: Product » 13; 

RankUnique defines the Rank Xerox product. It is defined in 
ProductFactoringProductsExtras4.mesa. 
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40.3 Index of Interface Items 



Item Page 

Converter: Product 1 

. OFonts: Product 1 

FujiUnique: Product 2 

Fuji2Unique: Product 2 

Languages: Product 2 

OahuUnique: Product 2 

PFonts: Product 1 

Product: typ€ 1 

RankUnique: Product 2 

Services: Product 1 

Services2: Product 2 

Star: Product 1 

Viewpoint: Product 1 

ViewPointApps: Product 1 
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PropertySheet 



41.1 Overview 

The PropertySheet interface allows clients to create property sheets. A property sheet 
shows the user the properties of an object and allows the user to change these properties. 
Several different types of properties are supported. The most common ones are boolean, 
choice (enumerated), and text. (See Figure 41.1.) 




Figure 41.1. A Property Sheet 



From a client's point of view, a property sheet is a Star window shell with a form window as 
a body window. See the StarWindowShell and FormWindow interfaces. The FormWindow 
interface especially must be understood in order to create a property sheet. 

A property sheet is created by calling PropertySheet.Create, providing a procedure that will 
make the form items in the form window (a Formwindow.MakeltemsProc), a list of 
commands to put in the header of the property sheet, such as Done, Cancel, and Apply 
(PropertySheet.Menultems), and a procedure to call when the user selects one of these 
commands (a Prop«rtySheet.MenultenriProc). PropertySheet. Create returns the 
StarWindowSheil.Handle for the property sheet. When the user selects one of the commands in 
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the header of the property sheet, the client's PropertySheet.MenuitemProc is called. If the 
user selected Done , for example, the client can then verify and apply any changes the user 
made to the object's properties. 

PropertySheet also provides the capability to create linked property sheets. Several 
property sheets may be logically linked together in the same property sheet shell. This is 
accomplished by changing form windows within a property sheet's Star window shell; and 
by having an additional choice item that specifies which form window is currently 
displayed. Linked property sheets are further described in the section on Linked Property 
Sheets below. 

41.2 Interface Items 

41J2.1 Create a PropertySheet (Not a Linked One) 

Create: procedure [ 

form Window! terns: Formwindow.MakeltemsProc, 
menultemProc: MenuitemProCr 
size: window.Oims, 

menuitems: Menultems «-propertySheetOefaultMenu, 
title: xstnng.Reader 

piaceToDispiay: window.Place ^ nullPlace, 

f ormWindowltemsLayout:FormWindow.LayoutProc 4- nil, 

window AttachedTo: starwindowSheii.Handle 4- [nil]. 

giobalChangeProc: FormWindow.GlobaiChangeProc <- nil, 

display: soolean 4-true, 

clientOata: long pointer «- nil, 

afterTakenOown: MenultemProc <- nil, 

zone: uncounted zone <- nil] 

RETURNS [shell: StarWindowSheil.Handle]; 
Create creates a property sheet. 

formWindowltems is a client-supplied procedure that is passed a body window of the 
property sheet. It should fill the window with the form items that make up the main body of 
the property sheet. (See the Form Window interface for a full description of how to create 
form items in a window.) 

menultemProc is a client-supplied procedure that is called whenever the user selects one of 
the menu items in the header of the property sheet window. (See §41.2.2 below.) 

size is the preferred size of the property sheet star window shell. 

menuitems specifies the menu items that are displayed in the header of the property sheet. 
The default is ? {help), Done, and Cancel. 

title is the title to be displayed in the header of the property sheet. 

piaceToOisplay is the preferred location on the screen of the property sheet. If the default is 
taken. Create will calculate the place to display. 

formWindowltemsLayout specifies the desired position of the form items in the 
FormWindow. (See FormWindow.LayoutProc for a full description.). If 
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formWindowltemsLayout is nil, then FormWindow.OefaultLayout of one item per line is 
used 

window AttachedTo is the StarWindowSheli that this property sheet is showing properties 
for. If windowAttachedTo is not nil, then the user will not be able to close 
windowAttachedTo until this property sheet is closed. (See also 
starWindoMrSheii.Create.host.) 

globalChangeProc is called if any item in the main form window is changed. (See 
FprmWindowr.GlobalChangeProc for a full description). 

display indicates whether the property sheet should actually be displayed on the screen 
(inserted into the visible window tree) or just created but not actually painted on the screen 
(not inserted into the visible window tree). If this is a property sheet for a file (i.e., if it is 
being created as the result of a call to a Containee.GenericProc [atom: Props]), then display 
should be false and the StarWindowSheli. Handle should be returned from the GenericProc so 
that, for example, the desktop implementation can put the property sheet on the display by 
calling StarWindowSheii.Push. 

cJientOata will be passed to formWindowitems, formWindowltemsLayout, and 
menultemPrOC. Fine Point: formWindowltttms will not be called after Cr«ate returns and therefore may be 
nested. 

The afterTa ken Down is called after the property sheet has been removed from the screen. 
The return parameter of the MenultemProc is ignored in this case. Note: Clients must still 
provide a regular MenultemProc. 

Clients may pass in a zone to be used instead of the default zone created by the 
StarWindowSheli implementation. 

shell is the property sheet, shell will be a bitmap-under window if storage space is 
available. Clients who desire a property sheet without a bitmap-under should use 
CreateWithBitmapUnderOption. The typical property sheet should be a bitmap-under 
window since bitmap-under windows are moved and deleted faster than non bitmap-under 
windows. 

nuilPiace: window.Place; 

nuilPlace defines the default for placement of a property sheet. If the default is used, the 
property sheet is placed at an appropriate place on the screen. 

CreateWithBitmapUnderOption: procedure [ 
f orm Wi ndowi tems : Form window. IVIa keite msProc, 
menultemProc: l\/lenultemProc, 
size: window.Oims, 

menultems: IVIenultems 4-propertySheetOefauitlVlenu, 

title: xstring.Reader «-nil, 

piaceToOispiay: window.Place f- nullPlace, 

f orm Window! temsLayout: Form Window. LayoutProc «- nil, 

windowAttachedTo: starWindowSheii.lHandle «-{nil], 

globalChangeProc: Formwindow.GlobalChangeProc 4- nil, 

display: boolean 4~true. 

ciientOata: long pointer «- nil. 

afterTakenOown: MenultemProc nil. 

bitmapOption: starWindowSheilExtra5.BitmapUnderOption *- noBitmapUnder, 
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zone: uncounted zone*- nil] 

RETURNS [shell: StarWindowShelLHandle]; 

CreateWithBltmapUnderOption is identical to Create except for the additional parameter 
bitmapOption. If bitmapOption is noBitmapUnder, no attempt is made to make the 
property sheet a bitmap-under. If bitmapOption is bitmapUnder or maybeBitmapUnder, 
the property sheet will be a bitxnap-under window if enough storage space is available. 
Clients must use CreateWithBltmapUnderOption to create a property sheet without a 
bitmap-under since a property sheet created through Create is automatically a bitmap- 
under window if storage space is available. Clients of CreateWithBltmapUnderOption 
need not be concerned with managing the bitmap-under storage. Fine Point: This procedure is 
currently exported througii PropertyShaetEztra. 

41.2.2 Menu Items and the MenuItemProc 

MenultemType: type « {done, apply, cancel, defaults, start, reset}: 
Menuitems: type « packed array MenultemType of BooleanFalseOefauit; 
BooieanFaiseOefault: type a boolean 4- false 

propertySheetOefauitMenu: Menuitems » [done: true. apply: true. cancel: true]; 
optionSheetOefaultMenu: Menuitems « [start: true, cancel: true]: 

The client specifies a set of commands to be placed in the header of the property sheet. 
MenultemType specifies all of the possible commands. Menuitems specifies a set of these 
commands and is passed to PropertyShe«t.Create. propertySheetOefauitMenu and 
OptionSheetOefaultMenu specify two common sets of commands. 

MenuItemProc: type » procedure ( 

shell: StarWindowShell.Handle, 
formWindow: window.Handle, 
menultem: MenultemType] 
returns [ok: boolean false]; 

The client supplies a MenuItemProc when a property sheet is created. It is called whenever 
the user selects one of th&menu items in the header of the property sheet. formWindow is 
the main form window of the property sheet, menultem is the type of menu item that the 
user selected. The client typically (when the user selects Done or Apply) retrieves the 
values of the items that the user edited (using FormWindow. HasChanged and 
FormWindow.GetXXXItemValue procedures), verifies that the values are meaningful (for 
example, numbers that are within proper range), and applies the new values to the 
properties of the object this property sheet represents. 

The return parameter ok has slightly different meanings in the following two cases: 

1. For an ordinary property sheet (not a linked property sheet), the MenuItemProc is 
called when the user selects a command and the return parameter indicates whether 
the property sheet should be destroyed. 

2. For a linked property sheet, the MenuItemProc is called both when the user selects a 
command in the header (in which the case above applies) and when the client calls 
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SwapExistingFormWindows or SwapForm Windows with apply a true. In this case 
the MenuitemProc is called to allow the client to apply any changes made to the form 
window sheet being linked from. The menultem parameter will be "done"; the return 
parameter indicates whether to allow the swap to actually occur, ok ■ false indicates 
that there is something invalid in the form window and the client does not want the 
swap to occur (the client typically posts a message before returning). If ok » true, the 
swap occurs. 

Note: The client need not worry about these cases when writing the MenuitemProc, but 
can simply write the "done" code as usual. If the user selects Done and the MenuitemProc 
returns ok ■ true, the property sheet is destroyed. If the user links to another sheet on a 
linked property sheet and the MenuitemProc returns ok « true, the sheets are swapped, 
rather than the whole property sheet being destroyed. 

41.2.3 Linked PropertySheets 

Several property sheets may be logically linked together in the same property sheet. This 
is accomplished by changing form windows within a property sheet's Star window shell, 
and having an additional choice item that specifies which form window is currently 
displayed. See Figure 41.2 below. 



Form Window 




Display 



Tag I BOOLEAN j Suffix 

I CHOICE 1 ICHQICEa | CHOICeT] 



Tag I Text item 



i 



T 



Figure 41.2 A Linked Property Sheet 



41-5 



41 PropertySheet 



This additional choice item actually resides in an additional form window, called a link 
window. This link window is another body window of the Star window shell. The link 
window remains visible all the time, while the main form window may be swapped. The 
client does this by supplying a FormWindow.ChoiceChangeProc for the single choice item in 
the link window. Then when the user selects a new choice for that item, the client (in the 
ChoiceChangeProc) calls SwapForm Windows or SwapExistingForm Windows to change 
the main form window. Note: Only one main form window is installed in the Star window 
shell at a time. A linked property sheet is created by calling CraateLlnked. 

CreateLinked: procedure [ 

formWIndowltems: Formwindow.MakeltemsProc, 
menultemProc: MenultemProc, 
size: wfndow.OimSr 

menuitems: Menultems 4-propertySheetDefaultMenu, 
title: xstring.Reader 4-niu 
placeToOisplay : window.Ptace *- nuilPlace, 
formWindowltemsLayoutiFormwindow.LayoutProc «-nil, 
windowAttachedTo: starwindowSh«ii.Handle 4-{nil], 
giobalChangeProc: Formwindow.GlobalChangeProc «-nil, 
display: boolean 4-true. 
linkWindowltemsrFormWindow.MakeltemsProc, 
linkWindowltenisLayout:Fonnvvindow.LayoutProc«-Niu 
clientOata: long pointer4-nil. 
afterTakenOownProc: MenultemProc <- nil. 
zone: uncounted zone 4-nil] 

RETURNS (shell : StarWindowSheil-Handle]; 

CreateLinked creates a linked property sheet. Creating a linked property sheet is almost 
identical to creating an ordinary property sheet, (see Create above for a full description of 
all the parameters), except CreateLinked has the additional parameters linkWindowitems 
and linkWindowltemsLayout. linkWindowitems is called to make the choice item in the 
link window. It should create a single choice item with a FormWindow.ChoiceChangeProc. 
linkWindowltemsLayout is called to specify the position of the choice item in the link 
window. The default places the item appropriately in the link window, so most clients will 
want to take the default for linkWindowltemsLayout. Note: formWIndowltems and 
formWindowltemsLayout specify the main form window that is initially visible in the 
property sheet. 

CreateLinkedWithBitmapUnderOption: procedure [ 
formWIndowltems: Formwindow.MakeitemsProc, 
menultemProc: MenultemProc, 
slze:window.Dims, 

menuitems: Menuitems •H-propertySheetOefaultMenu, 
title: xstring.Reader 4-NiL, 
placeToOisplay: window.Piace nullPiace, 
formWindowltemsLayout :Formwindow.LayoutProc nil, 
windowAttachedTo: starWindowShell.Handle «-(nil], 
giobalChangeProc: Formwindow.GlobalChangeProc <-nil, 
display: boolean 4-true, 
linkWindowitems: FormWindow.MakeltemsProc, 
linkWindowltemsLayout:Formwindow.LayoutProc4-NiL, 
clientOata: long pointer <- nil. 
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afterTakenOownProc: MenultemProc <-nil. 

bitmapOption: starWindowSheiiExtra5.BitmapUnderOption«-noBitniapUnder, 
zone: uncounted zone nil] 

RETURNS (shell: StarWindowSheil-Handle]; 

CreateLlnkedWithBitmapUnderOption is identical to CreateLinked except for the 
additional parameter bitmapOption. See CreateWithBitmapUnderOption for an 
explanation of the bitmapOption parameter. Fine Point: This procedure ia currently exported 
through PropertySheetExtra. 

SwapFormWindows: procedure [ 
shell: StarWindowShelLHandle, 

newFormWindowitems: FormWindow.MakeitemsProc. 
newFormWIndowltemsLayout: Form Window. LayoutProc *- nil, 
apply: boolean 4- true, 
destroyOld : boolean 4- true, 
newMenuitemProc: MenuitemProc 4-nil, 
newMenultems: Menultems 4- all(falsel 
newTitle: xstring.Reader 4-NIL, 

newGtobalChangeProc: FormWindow.GlobalChangeProc ^-nil, 
newAfterlakenOownProc: MenuitemProc «-NiL] 
RETURNS [old: window.Handle]; 

SwapFormWindows swaps the main form window of a property sheet with a new one. This 
will usually be called from the Formwindow.ChoiceChangeProc of the choice item in the link 
window. May raise Error [notAPropSheet]. 

shell is the property sheet. 

newFormWindowitems supplies the items for the new window. 

newFormWIndowltemsLayout specifies the layout for the items in the new form window. 

apply speciHes whether any changes to the current form window should be applied before 
the swap. If apply ■ true, the current MenuitemProc for shell is called with menultem « 
apply. If apply ■ false, the MenuitemProc is not called. 

The destroyOld parameter indicates whether the old form window should be destroyed or 
not. If destroyOld a false, then the return parameter is the old form window, else the 
return parameter is nil. This allows clients to perform the following typical sequence of 
events: 

1. Create a linked property sheet using CreateLinked. 

2. The first time the user links to another sheet, call SwapFormWindows with 
destroyOld ■ false and save the old form window. 

3. When the user goes back to the first sheet, call SwapExistingFormWindows, supplying 
the previously saved old form window, and thus avoiding having to create the first form 
window again. 

newMenuitemProc allows the client to install a different MenuitemProc than the one that 
was supplied with CreateLinked. 

newAfterTakenOownProc allows the client to install a different takedown MenuitemProc 
than the one that was supplied with CreateLinked. 



41-7 



41 PropertySheet 



newMenultems, newTitle, and newGiobalChangeProc allow the client to change these as 
well. 

If the default newMenuitemProc, newMenultems, newTitle, or newGlobaiChangeProc is 
taken, the current values are retained. 

SwapExistingForm Windows: procedure ( 
shell: starwindowSh«ii.Handle, 
new: window.Handle. 
apply: boolean <-true, 
newMenultemProc: MenultemProc 4>niu 
newMenultems: Menultems 4- all(false], 
newTitie: xstring.Reader <-nil, 
newAfterTakenOownProc: MenultemProc 4-nil] 
RETURNS [old: window.Handle]; 

SwapExistingForm Windows swaps the main form window of a property sheet with a new 
one. The new form window must already exist. If it does not, use SwapForm Window, new 
is the new form window, apply, newMenultemProc, newMenultems, and newTitie are the 
same as in SwapForm Window, old is the previous main form window. May raise Error 
[notAPropSheet]. 

41.2.4 Miscellaneous 

GetFormWindows: procedure [shell: starwindowSheii.Handle] 
RETURNS [form, link: window.Handle]; 

GetFormWindows returns the current form windows of shell. If shell is not a linked 
property sheet, link is nil. May raise Error [notAPropSheet]. 

InstailFormWindow: procedure [ 
shell: StarwindowSheii.Handle, 
menultemProc: MenultemProc, 
menultems: Menuitems «- property SheetOefaultMenu, 
title: xstring. Reader 4- NiL« 
form Window: window.Handle, 
afterTakenOownProc: MenultemProc 4- nil]; 

InstailFormWindow installs formWindow in shell. May raise Error [notAPropSheet]. 

41.2.5 Signals and Errors 

Error: error [code: ErrorCode]; 
ErroKode: type « {notAPropSheet}; 

Error [notAPropSheet] is raised if a StarwindowSheii.Handle that is not a property sheet is 
passed to a PropertySheet procedure . 
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41.3 Usage/Examples 

41.3.1 Flow Description of Creating a Property Sheet 

The following describes the sequence of calls involved in creating and taking down a 
property sheet, including Viewpoint interfaces and clients. 

1. Client calls Prop«rtySh«et.Create, supplying a Formwindow.MakeltemsProc, a 
FormWindow.LayoutProc (optional), and a Property S)M«t.MenulteniProc. 

2. Prop«rtySh««t.Create creates a Star window shell and a body window inside the 
StarWindowSheii. It then calls FormWindow.Create, passing in the body window. 

3. Formwindow.Create calls the client's Formwindow.MakeltemsProc. 

4. The client's FormWindow.MakeitemsProc creates the items in the property sheet by 
calling various Formwvindow.MakeXXXItem procedures. 

5. Form Window. Create calls the client's Form window. LayoutProc. If the client did not provide 
one, a default LayoutProc provided by FormWindow is called. 

6. The FormWindow. LayoutProc makes calls to FormWindow. AppendLine and 
FormWindow.Appendltem to specify the layout of the items created by the 
Formwindow.MakeltemsProc. 

7. Formwindow.Create returns to PropertySheet.Create. PropertySiieet.Create returns to the 
client. The client returns to the notifier process. 

8. The property sheet is now on the screen and the notifier process is waiting for the user. 

9. The user changes some values in the property sheet. This is all managed by 
FormWindow; the client gets called only if there is a FormWindow.BooleanChangeProc 
or FormWindow.ChoiceChangeProc or FormWindow.GlobalChangeProc. 

10. The user selects Done in the header of the property sheet. 

11. A procedure inside of PropertySheet is called. PropertySheet calls the client's 
Prop«rtySii««t.MenultemProc. 

12. The client's Prop«rtySli««t.MenuitemProc checks for any changed values 
(Pormwindow.HasBeenChanged and FormWindow.HasAnyBeenChanged) and calls the 
appropriate FormWindow.GetXXXItemValue to obtain the new values. The client 
validates and applies these new values, then returns an indication of whether the 
property sheet should be taken down. 

13. PropertySheet takes down the property sheet and returns to the notifier. 

14. END. 
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41.3.2 An Ordinary Property Sheet 

This example creates a property sheet from some arbitrary properties and then applies the 
user's changes to those properties. It uses a rather contrived set of properties described by 
Properties and PropertiesObject. In general, a real property sheet would get its properties 
from some real object. This example will produce the property sheet shown in Figure 41.1. 

Property5heet£xainple.mesa 

DIRECTORY 

FormWindow using [ 

Choiceitem, GetBooieanltemValue, GetChoiceltem Value, GetTextltemValue, 
HasAnyBeenChangedr HasBeenChanged, ItemKey, MakeBooleanitem, 
MakeChoiceltem, MakeitemsProc, MakeTextltem, SetBooleanitem Value, 
SeKhoiceltemVaiue, SetTextitem Value], 

PropertySheet using [Create, MenuitemProc], 

StarWindow Shell using [Handle], 

XString using [FreeReaderBytes, FromSTRlNG, ReaderBody], 
Window USING [Handle]; 

PropertySheetExample: program imports FormWindow, PropertySheet, XString a { 

Properties: TYPE ■ long pointer to PropertiesObject; 

PropertiesObject: type ■ record [ 
boolean: boolean, 
choice: Choices, 
text: XString. ReaderBody]; 

Items: type » {boolean, choice, text}; 

Choices: TYPE ■ {choice1,choice2, choices}; 

zone: uncounted zone <-...; 

MakeProperty Sheet: procedure [props: Properties] 

RETURNS [shell: StarWindowSheil.Handle] » { 

title: xstring.ReaderBody 4- xstring.FromSTRlNG [''Title"L]; 

shell <-PropertyShe«t.Create [ 
formWindowltems: Makeltems, 
menultemProc: MenultemProc, 
menuitems: [help: true, done: true, cancel: true, 

apply: true, defaults: true], 
size: [w: 300, h: 200], 
title: ©title, 
ciientData: props]; 

}; 
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Makeitems: Formwindow.MakeitemsProc a { 
props: Properties dientOata; 
"^^^ tag: XString.ReaderBody 4-xstrmg.FromSTRING('*Tag"L]; 

BEGIN 

label: xstnng.ReaderBody 4-xstring.FromSTRING("BOOLEAN"L]; 
suffix: xstring.ReaderBody <~xstring.FromSTRING('*suffix'*L]; 
PormWindow.MakeBooleanltem [ 

window: window, 

myKey: ltems.booiean.ORD, 

tag: ©tag, 

suffix: ©suffix. 

label: [string [label] ], 

initBooiean: props.boolean ]; 
end; 

BEGIN 

c1 : xstring.ReaderBody <-xstring.FromSTRlNG{"CHOiCE 1"L]; 
c2: xstring.ReaderBody <-xstring.FromSTRING("CHOICE 2"L]; 
c3: xstring.ReaderBody <-xstring.FromSTRtNG(*' CHOICE 3''L]; 
choices: array [0..3) of Formwmdow.Choiceltem 4- [ 

[string(Choices.choice1 .ord, c1 ] ], 

[string[Choices.choice2.0RD, c2] ], 

[string[Choices.choice3.0RD, c3] ] ]; 
Formwindow.MakeChoiceitem [ 

window: window, 
""^^ myKey: Items.choice.ORD, 

values: OESCRiPTOR(choices], 

initChoice: props.choice.ORo]; 
end; 

FormWindow.MakeTextitem [ 
window: window, 
myKey: ltems.text.0R0, 
tag: @tag, 
width: 40, 

initString: ©props.text ]; 

}; 

MenultemProc: Property sheet. Men ultemProc ■ { 
props: Properties <-cllentData; 
SELECT menultem from 
heip a > . . . ; 

done ■ > RETURN[destroy: ApplyAnyChanges[formWindow, propsl.ok]; 
cancel ■ > RETURN[destroy: true]; 

apply ■ > [] <--AppiyAnyChanges(formWindow, props]; 
defaults > > SetOefaults[form Window, props]; 
endcase a > error; 
RETURN(destroy: false]; 

W }; 
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AppiyAnyChanges: proc [window: window.Handie, props: Properties] j 

RETURNS [ok: boolean] a BEGIN 

IF -FormWindow.HasAnyBeenChanged [window] then return [ok: true]; 
FOR eachitem: Items in Items oo 

ItemKey: FormWindow.ltemKey » eachitem.ORO; 

IF -Formwindow.HasSeenChanged [window, itemKey] then loop; 

SELECT eachitem from 

boolean » > props.booiean ^Formwindow.GetBooieanltemVaiue(window, itemKey); 
choice ■ > props.choice4>VAL(FomiWindow.GetChoiceltemVaiue[window, ItemKey] ]; 
text ■ > { 

xstring.FreeReaderBytes [r: @props.text, z: zone]; 
props.text 4-FormWindow.GetTextltemVaiue [window, itemKey, zone]}; 
enocase; 
enoloop; 
RETURN [ok: true]; 
end;- AppiyAnyChanges 

SetOefauits: proc [window: window.Handie, props: Properties] » 

BEGIN 

defauitText: xstring.ReaderBody 4-xstring.FromSTRlNG[''Text item"L]; 
Formwindow.SetBooleanltem Value [ 

window: window, 

item: Items.booiean.0RO, 

newValue: FALSE]; 

Formwindow.SetChoiceltemValue [ ^ 

window: window, 

item: ltems.choice.ORD, 

newValue: Choices.choice2.0Ro]; 
Formwindow.SetTextltemVaiue [ 

window: window, 

item: ltems.text.0RD, 

newValue: ©defauitText]; 
end; 

}... 
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41.4 Index of Interface Items 



Item Page 

BooieanFaiseOefault: type 4 

Create: procedure 2 

OeateLinked: procedure 6 

CreateWithBitmapUnderOption: procedure 3 

OeateUnkedWithBitmapUnderOption: procedure 6 
Error: error . 8 

ErrorCode: type 8 

GetFormWindows: procedure 8 

InstaiiFormWindow: procedure 8 

MenultemProc: type 4 

Menuitems: type 4 

MenultemType: type 4 

nuilPlace: windovtf.Place 3 

optionSheetOefauitMenu: Menuitems 4 

propertySheetDefaultMenu: Menuitems 4 

SwapExistingFormWindows: procedure 8 

SwapFormWindows: procedure 7 
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42.1 Overview 

Prototype manipulates prototype files. A prototype file is a blank copy of an application's 
file that the user can copy. Prototype files are in the Directory icon under '*Blank 
Documents, Folders, etc." 

A prototype file resides in the prototype catalog (see the Catalog interface) and is uniquely 
identified by it is file tsrpe, subtype, and version. The subtype distinguishes between objects 
of the same file type, such as the blank document and the basic graphics transfer 
document. Subtjrpe is stored in an extended attribute on the prototype file. A nonexistent 
subtype is equivalent to subtype 0. 

Version is stored in the BWS-standard version extended attribute (see 
BWSAttributeTypes). The intent is that clients need only examine the version to determine 
if the prototype is current. A nonexistent version attribute is equivalent to version 0. 

Prototype provides Find and Create procedures. A client typically calls Find and if it 
returns NSFito.nullReference, then call Create. 

42.2 Interface Items 

Version: type ■ cardinal; 
Subtype: type ■ cardinal; 

Find: procedure [type: NSFii«.Type, version: Version, 

subtype: Subtype 4-0, session: NSFii«.Session 4-NSFii«.nuliSession] 
RETURNS [reference: NSFii«.Reference]; 

Find returns a reference for the file with the specified type, version, and subtype. If the file 
does not exist, NSFito.nullReference is returned. 

Create: procedure [ 

name: xstring.Reader, 
type: NSFii«.Type, 
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version: Version, jgm^ 

subtype: Subtype *- 0, 

size: long cardinal «-0, 

isOirectory: boolean 4- false, 

session: NSFti«.Session 4>NSFii«.nuilSession] 

RETURNS [prototype: NSFii«.Handle]; 

Creates a file in the prototype catalog with the specified name, type, version, subtype, size 
in bytes, and isOirectory attribute. 

Add: PROCEDURE [file: NSFit«.Handle, version: Version, 

sulitype: Subtype session: NSFii«.Session 4-NSFii«.nullSession]; 

Moves an already existing file into the prototype catalog, assigning it the given version 
and subtype. Fina point: Thia ia in PrototypeExtra in ViewPoint. 

PurgeOldVersions: procedure [type: NSPil«.Type, current: Version, suistype: Subtype 4- 0]; 

Deletes any versions of the given prototype that are older (smaller number) than current. 
PurgeOldVersions assumes that higher version numbers are more recent than lower 
version numbers. If this is not true for your version numbers, do not call this operation . 

42.3 Usage/Examples 

This is an example of a procedure that an application probably calls at initialization time. ^^^^ 

sampiekonFtleType: NSFite.Type » ; 

version: cardinal • . . . ; 

FIndOrCreatelconFiie: procedure ■ { 

name: xstring.ReaderBody 4-xstring.FromSTRIN<a(**Sample Icon^L]; 

This name should really come from XMessage. 
iP(Prototyp«.Find [ 

type: samplekonFlleType, version: version] ■ NSFii«.nullReference) then 
NSFiia.Oose [prototypc.Create [ 

name: ©name, type: samplelconFileType, version: version] ]; 

}; 
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Item 


Page 


Add: PROCEDURE 


2 


Create: procedure 


1 


Find: procedure 


1 


PurgeOldVersions: procedure 


2 


Subtype: type 


1 


Version: type 


1 
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43.1 Overview 

Scrollbar provides the means of attaching scrollbars to windows. Clients provide a 
number of procedures that perform various scrolling actions. For a comprehensive view of 
ail the subwindow interfaces and their intended use, see the Subwindow Overview chapter. 

43.2 Interface Items 

43.2.1 Attaching Scrollbars 

Attach: PROCEDURE [ 

window: window.Handle, 
vertical,, horizontal: boolean «-true. 
single: SingleScroUProc 4~nil, 
jump: JumpScroUProc 4-nil. 
scrollbar Info: Scrollbar InfoProc «--nil, 
thumb: ThumbScrollProc <-nil. 
feedback: ThumbFeedbackProc 4-nil, 

zone: UNCOUNTED ZONE]; 
Type: type a {horizontal, vertical}; 

Attach will attach a scrollbar of type to window. Scrollbars are younger siblings of the 
viewer (window) they are attached to. single is the proc that will be called when the user 
invokes scrolling in one of the arrows or paging symbols (+ -). jump scrolling is currently 
not implemented, thumb is called when the user points down in the thumbing region, 
feedback is called for each mouse action to allow the client to provide interim feedback like 
a sideways arrow, scrolibarinfo will be called after thumb to get the percentage and offset 
information needed to paint the thumbing feedback in the scrollbar. 
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Adjust: PROCEDURE [window: window.Handlel; 

Should be called when window is changing size to allow the attached scrollbars to adjust 
their size accordingly. Should also be called after the call to Attach to establish initial size. 

Destroy: procedure (window: window.Handle, type: Type): 

Destroys the context associated with the scrollbar of type that is attached to window. 

43.2.2 Scroll proc TYPES and PROCS 

In each of the following procedure types, window refers to the viewer of the subwindow 
that the scrollbars are attached to. type refers to the specific scrollbar on the viewer, 
horizontal or vertical. 

SingleScrollProc TYPE » proci 
window: window.Handle, 
flavor: SingleScroilFlavor, 
amount: natural, 

arrowScroll Action: ArrowScrollAction *-qo, 
type: Typei; 

SingieScroilFlavor: type > {pageFwd. pageBwd, forward, backward}: 
ArrowScrollAction: type a {start, go, stop},- 
defauitSmoothScrollAmount: natural; 

A SingleScrollProc is the basic scrolling proc that should provide for forward, backward 
continuous scrolling, and pageFwd, pageBwd paging. It is called whenever the user points 
at an arrow or the plus or minus sign in a scrollbar. Scroll distance will be determined by 
amount. If flavor is forward or backward then amount is in screen dots. 
(defaultSmoothScrollAmount can be used by the caller if desired). If flavor is pageFwd or 
pageBwd then amount is in pages. A SingleScrollProc is called with arrowScroll Action « 
start when the user begins the scrolling action. SingleScrollProc is called with 
arrowScrollAction « go for each successive call until the user terminates scrolling. At 
termination arrowScrollAction a stop. The SingleScrollProc will be called repeatedly as 
long as the user has the mouse button down over one of the arrows, thus producing 
continuous scrolling. 

JumpScrollProc: type « proci 
window: window.Handle, 
direction: JumpScrollFlavor, 
percent: Percent], 
type: Type; 

JumpScrollFlavor: type » (forward, backward}; 
Percent: TYPE » (0..1001: 
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The client may provide a JumpScrollProc for Tajo-like jump scrolling, percent is relative to 
window. Currently not implemented. 

ScroilbarinfoProc: type at proc( 
window: Window.Handle, 
type: Typei 

RETURNS [offset, portion: Percent]; 

The clients ScroilbarinfoProc is called to get information to properly paint the thumbing 
region whenever the user has scrolled to a new position in the window. This is true 
whether the user is thumbing, paging or continuous scrolling. The client returns the 
offset from the beginning of the object and portion (percentage of the entire object) that is 
visible in the viewer. The scrollbar display will be updated using this information to 
properly paint the thumbing region (tajo gray bar, star diamond, etc.) 

ThumbWithin: type » {all, page, other}; 

ThumbAction: type a {.down, track, up}: 

In the following procedures within equates percent with an extent: 
all 3 > percent is relative to the entire object, 
page a > percent is relative to a client defined page, 
other a > is currently unused. 

ThumbFeedbackProc: type « proci 
window: window.Handle, 
percent: Percent, 
within: ThumbWithin <~ all, 
type: Type, 
action: ThumbAction]; 

The ThumbFeedbackProc is provided to allow the client an opportunity to display his own 
feedback to the user concerning the relative location of the thumbing action DURING 
thumbing. Traditionally this feedback has been in the form of page numbers or a sideways 
arrow in the cursor, and/or information in the scroUliar itself (such as the Star diamond). 
ThumbFeedbackProc is first called when thumbing is invoked (user points down in the 
thumbing region of the scrollbar) with action » down. If the user moves the cursor the 
proc will be called again with action ■ track. When the user buttons up the proc will be 
called with action. • up. Clients should be aware that it is possible to never get the last 
call. The user may abort the thumb activity by either performing the pointUp outside of 
the scrollbar or by pressing the STOP key. The scrollbar code will be prepared to reset the 
Cursor but no other clean up will be provided. 

ThumbScrollProc: type a proc[ 
window: window.Handle, 
percent: Percent, 
within: ThumbWithin «-all, 
type: Type]; 

The ThumbScrollProc is the procedure that actually performs the scroll. It is called when 
the user completes the thumb activity by pointing up in the thumbing region. The 
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procedure is expected to make the appropriate calls to Window. SlideAndSize to cause the 
scroll to happen. 

GetScroilProcs: procedure (window: window.Handle. type: Type! 

RETURNS ( 

single: SingleScroiiProc, 
jumpJumpScrollProc 
scroilbarlnfo: ScroilbarlnfoProc 
thumb: ThumbScroiiProcU 
feedbaclc: ThumbFeedbackProci; 

Returns the client scrollProcs associated with the viewer window and scrollbar type. 

SetSingieScroilProc: procedure ( 

window: Window. Handle, type: Type, scroll: SingleScrollProc] . 
RETURNS [old: SingleScrollProc]; 

SetlumpScroilProc: procedure ( 

window: window.Handle, type: Type, scroll: JumpScroilProc] 
RETURNS told: JumpScrollProc]: 

SetScrollbarinfoProc: procedure ( 

window: window.Handle, type: Type, scroll: ScroilbarinfoProc] 
RETURNS (old: ScrollbarlnfoProc); 

SetThumbScrollProc: procedure ( 

window: window.Handler type: Type, scroll: ThumbScroliProc] 
RETURNS [old: ThumbScrollProc]; 

SetThumbFeedbackProc: procedure [ 

window: Window.Handle, type: Type, scroll: ThumbFeedbackProc] 
RETURNS [old: THumbFeedbackPfOc]; 

Sets the various scrollProcs for window. 



43.2.3 UtiUties 



GetScrollbar: procedure [window:window.Handie. type: Type] 
RETURNS (scrollbar: Window.Handle]; 

Returns the scrollbar of type associated with window. Returns nil if there isn't one. 

GetScroiibarThickness: procedure returns [integer]; 

Returns the thickness of a scrollbar, i.e. the width of a vertical scrollbar or the height of a 
horizontal scrollbar. Useful for determining the overall size requirements for sub windows 
or shells. 

GetZone: procedure [window: window.Handle] 
returns [zone: uncounted zone]; 
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Returns the zone associated with window where window is the window the scrollbars are 
attached to. 

PercentOf : procedure [v: integer, p: Percent] 

RETURNS [INTEGER]; 

expresses p in terms of v 

example: m <- PercentOf [OutOfN, offset] 

Percentage: procedure [part full: integer] 
RETURNS [Percent]; 

returns the percentage of part to full 

example: offset <- Percentage(m. OutOf N] 

43.2.4 Errors 

Error: error [code: ErrorCode]; 

ErrorCode: type » (already Exists. doesNotExist}; 
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43.4 Index of Interface Items 



Item Page 

Adjust: PROCEDURE 2 

ArrowScrolIAction: type 2 

Attach: procedure 1 

defaultSmootScroilAmount: natural 2 

Destroy: procedure 2 

Error 4 

ErrorCode: type 4 

(aetScrollbar: procedure 4 

GetScrol I Procs : procedure 3 

GetScroiiThickness: procedure 4 

GetZone:pROCEDURE 4 

JumpScrollFlavor: type 2 

JumpScroilProc: procedure 2 

Percent: type 2 

Percentage: procedure 4 

PercentOf : procedure 4 

ScrolibarlnfoProc: type 3 

SeUumpScroiiProc: procedure 3 

SetScroilbarfnforProc: procedure 4 

SetSingieScroilProc: procedure 3 

SetThumbFeedbackProc: procedure 4 

SetlhumbScroilProc: procedure 4 

SingleScrollFiavor:TYPE 2 

SingleScroilProc: type 2 

ThumbAction:TYPE 3 

ThumbFeedbackProc: type 3 

ThumbScrollProc: type 3 

ThumbWithin: type 3 

Type: type 1 
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44.1 Overview 

The Selection interface defines the abstraction that is the user's current selection. It 
provides a procedural interface to the abstraction that allows it to be set, saved, cleared, 
and so forth. It also provides procedures that enable someone other than the originator of 
the selection to request information relating to the selection and to negotiate for a copy of 
the selection in a particular format. 

44.1.1 Requestors and Managers 

The Selection interface is used by two different classes of clients. Most clients wish merely 
to obtain the ualue of the current selection in some particular format; such clients are 
called requestors. These programs call Convert (or ConvertNumber, which in turn calls 
Convert), Query, or Enumerate. These clients need not be concerned with many of the 
details of the Selection interface. 

The other class of clients consists of those who wish to own or set the current selection; 
these clients are called managers. A manager calls Selection.Set and provides procedures 
that may be called to convert the selection or to perform various actions on it. The manager 
remains in control of the current selection until some other program calls S«iection.Set. 
These clients do need to understand most of the details of the Selection interface. 

The goal of the Selection interface is that the requestor need never know, and should never 
care, what module is managing the selection. All that matters is whether the selection can 
be rendered in a suitable form. For example, suppose the user presses COPY and selects a 
printer icon as the destination. The printer implementation needn't know what is printable 
and what isn't. It simply queries the selection to determine whether it can be rendered as 
an Interpress master, and if so it obtains it and sends it. Otherwise, it queries whether the 
selection can be enumerated as a sequence of Interpress masters (as would be true of a 
folder, for instance). If this also fails, the object is rejected. 

The selection is the expression of the user indicating the datum to be operated on. As such, 
it is conceptually owned by the user. The selection manager is a slave following the user's 
instructions. 
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To maintain this user interface model, the selection must only be changed at the explicit 
direction of the user. Software must allow the user to change the selection at will. To 
implement this user model, the selection Is only changed from within the user process or 
notifier. The notiiier is the system process that passes the user's actions, encoded as TIP 
results, to application software. 

Software that wishes to read the selection must deal with the fact that the selection may be 
changed at any time that the notifier process is running. The way to synchronize with this 
potentially asynchronous activity is to only read the selection in the notifier process. This 
guarantees that the selection will not be altered while it is being read. Application 
software running in the notifier process can be assured that the selection will not change 
until after the application returns to the system. Thus the first rule for dealing with the 
selection is: 

The selection may only be read or changed in the notifier process. 

Once an application returns to the notifier, any knowledge it retains about the selection 
may be invalidated at any instant when the user subsequently changes the selection. 
Similarly, if an application running in the notifier passes some information about the 
selection to another process, that information may similarly be invalidated at any time. In 
these circumstances, the application must copy the selection's value, using Copy, Move, or 
Copy Move, to assure that its data remains valid. Thus the second rule for dealing with the 
selection is: 

Copy the selections value before returning to the system or before passing it to another 
process. 

Copying the value of selection may not always be desirable. For example, if a selection 
requestor would like to copy a selection of files in the background, the requestor would not 
want to do a Copy before leaving the notifier; doing so would defeat the purpose of doing 
the filing operations asynchronously. To deal with the problem. Selection supports the 
notion of an encapsulated selection. While in the notifier, the requestor may ask that the 
selection be encapsulated. Doing so clears the user's selection, and saves the selection in a 
form that the selection manager can operate on from a non-notifler process. The requester 
can then call standard Selection requestor procedures passing in the encapsulated 
selection. 

44.1^ Essentials for a Requestor 

Clients that need the value of the current selection. 

44.1.2.1 Convert, Target, Value, Enumerate, CanYouConvert 

The fundamental operation performed by a selection requestor is to obtain the value of the 
current selection by calling Selection.Convert. Convert takes a Seiection.Target and returns a 
Selection. Value. The Target specifies what type of data the selection should be converted to. 
The Value contains a pointer to the converted selection. For example, Selection.Convert 
[target: string] will return a pointer to a string, i.e., an xstring. Reader. i^'lli 

Not all selections can be converted to all Targets; in fact most selections can be converted to 
only a small number of Targets. For example, if the selection is a text string, it can be 
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converted to Target string and perhaps to integer, but probably not to file or fiieType. Note: 
Converting to some Targets is not so much requesting the value of the selection as 
requesting some general information about the selection or its environment. For example, 
Selection.Convert [target: window] is a request for the window that the selection is in, 
S«l«ction.Convert [target: help] is a request for user help information about the selection, 
etc. Note that Target is an open-ended enumeration and that clients can create new 
Targets by using Siiiection.UniqueTarget. The type associated with each Target is 
determined by system-wide convention. Several of these TYPE/Target conventions are 
defined below under the description of Target. Other TYPE/Target conventions are 
documented in §44.2.1.1, Convert. 

A requestor can also enumerate the selection if it is more than a single item or if it can be 
split into smaller pieces. This is done by calling Seiaction.Enumerate. 

Finally, a requestor can determine what Targets the selection can be converted to without 
actually doing the conversion by calling s«i«ction.CanYouConvert, S«lection.Query, or 
S«laction.H O wH a rd . 



If a requestor would like to be able to operate on the selection from outside the notiiier, it 
can call Seiectionx. Encapsulate. This clears the user's selection. Some managers may often 
lock the object(s) in the selection so that the user can't operate on them while they are 
encapsualated. Once the requestor has an encapsulated selection, all of the standard 
operations are available: ConvertX, EnumerateX, CanYouConvertX, QueryX, and 
HowHardX (all presently in the SelectionX interface). These operations are identical to the 
standard operations (Convert, etc.) but take an additional parameter for the encapsulated 
selection. Typically a requestor would do the Encapsulate in the notifler process, then fork 
a process to operation on the encapsulated selection. 

44.1.2.2 Resource Allocation/Deallocation Considerations 



It is a strict rule that the Values produced by S«i«ction.Convert and s«lection.Enumerate 
describe objects owned by the selection manager. The requestor may examine the data 
referenced by the value field, but must not alter it. Furthermore, the requestor must free 
the Value (using Selection. Free) once he no longer needs it. 

If the requestor wishes to (1) keep the value after it returns to the system, or (2) pass the 
value to another process it must call Selection.Copy, S«l«ction.Move, or Selection.CopyMove. 
These in turn invoke a procedure supplied by the selection manager that modifies the 
Value such that the requestor may then make changes to value | without affecting the 
selection manager. Fine Point: The procedure supplied by the manager is returned by the manager as part of 
the Value record. If a Move is performed, the item is also deleted from the manager's domain. 
After the Move or Copy, any storage associated with the Value is now owned by the 
requestor. This storage may be freed by calling Seiection.Free. 

For example, Lf the current selection is a document icon, then Convert[file] yields a Value 
containing a long pointer to NSFiie.Reference for the file containing the document. If the 
requestor were to create a new document and associate it with the same file, it would 
probably have undesirable effects. Instead, the requestor should call Copy, passing in 
data:L0N6 pointer to NSFiie.Reference for the destination directory of the new file. When 
Copy returns, the Value contains a reference to a copy of the original file, and the requestor 
can use this freely. 
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As a second example, suppose the selection manager uses a Mesa string as the internal 
selection representation. Then Convertfstring] simply builds the string pointer into an 
xstring.Reader using xstring.FromSTRING. If the requestor wants to save the string for very 
long, he should call Copy, and the manager will allocate a copy of the original string using 
the zone passed to Convert. An alternative, somewhat simpler, is for the requestor to call 
xstring.CopyReader or xstring.CopyToNewReaderBody or xstring.CopyToNewWriterBody to 
copy the bytes, and then call Svioction.Free to dispose of the original Reader. 

An alternative to copying the selection before using it in another process is encapsulating 
the selection. See the discussion in §44.2.2.7. 

44.1.3 Essentials for a Manager 

Clients that own and manage the current selection. 

44.1.3.1 Set, ConvertProc, ActOnProc, ManagerData 

The implementor of a selection manager needs to know everything that the implementor of 
a selection requestor knows, plus more (see the previous section Essentials for a 
Requestor). 

The fundamental operation performed by a selection manager is to become the current 
manager by calling S«i«ction.Set. Set takes a ConvertProc, an ActOnProc, and a long pointer 
(ManagerData). 

The ConvertProc is called to obtain the value of the selection, whenever a requestor calls 
Selection. Convert or Seiection.Enumerate. The ConvertProc is also called to determine what 
Targets the selection can be converted to, whenever a requestor calls 
Seiection.CanYouConvert, Selection. Query, or Selection.HowHard. Conversion! nfo is a variant 
record passed to the ConvertProc that indicates which operation to perform: convert, 
enumeration, or query. 

The ActOnProc is called to perform various Actions on the selection, such as mark, unmark, 
clear, and encapsulate. 

The ManagerData passed to Set is passed back to the ConvertProc and the ActOnProc. 
Typically, the ManagerData identifies exactly what portion of the manager's domain is 
currently selected. For example, if the current selection is some text in a document, the 
actual manager is the document application, which has some ManagerData that indicates 
exactly which characters are currently selected. 

When a manager calls Seiection.Set, the previous manager is told to ActOn [clear], and 
Selection forgets about the previous manager. Hence, there is only one selection at a time. 
However, Selection also supports the notion of a "saved" selection. A client can become the 
current manager by calling Selection.SaveAndSet, which does a Set but also saves the 
previous selection. Later, the manager that did the SaveAndSet can do a Seiection.Restore, 
which restores the previous selection. 

Related to the notion of a saved selection is an encapsulated selection. The difference 
between the two is that a saved selection cannot be operated on until it is restored. An 
encapsulated selection can be operated on using the ConvertX, EnumerateX, etc. operations 
that all take a parameter for the encapsulated selection. To encapsulate the selection, the 
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requestor calls SeiectionX. Encapsulate which calls the managers's ActOnProc with action 
unmark followed by ActOn(encapsulate]. The manager is expected to modify its manager 
data that was passed into Set to note that the selection is saved. Th manager should also 
lock down the objects in the selection if necessary or do whatever is necessary to insure that 
the objects in the selection will remain accessible until the encapsulated selection is freed. 
When the requestor later operates on the encapsulated selection, the manager's ActOnProc 
and ConvertProc will be called with the manager data that was originally passed into 
Selection. Set. 



44.1.3.2 More on Selection. Value, ValueFreeProc, and ValueCopyMoveProc 

The Value produced by a manager's ConvertProc contains more than simply a pointer to 
the converted selection. It also contains a pointer to two procedures, a VaiueFreeProc and a 
ValueCopyMoveProc. The VatueFreeProc is called when the requestor calls Selection. Free so 
that the manager can release any resources that were allocated when the selection was 
converted. The manager's ValueCopyMoveProc is called when the requestor calls Copy, 
Move, or CopyMove. The ValueCopyMoveProc should copy or -move the converted 
selection value so that the manager no longer owns the resources associated with the 
value. A third field in the Value record is a long unspecified that may be used to store data 
for the VaiueFreeProc and the ValueCopyMoveProc. 

If the converted selection value can be copied or moved, the manager must return a 
ValueCopyMoveProc with the Value. For example. Targets string and file can be moved or 
copied, while it does not make sense to move or copy Targets window and fileType. The 
ValueCopyMoveProc modifies the Value such that the requestor may then make changes 
to value f without affecting the selection manager. If a Move is performed, the item is also 
deleted from the manager's domain. (Some managers may implement Copy but raise 
ErrorlinvalidOperationl if asked to do a Move.) The interpretation of the data given to a 
ValueCopyMoveProc depends on the manager; the typical use is to specify a destination for 
the object. 



44.1.3.3 Storage Considerations for ConvertProc 

As stated above, it is a strict rule that the Values produced by the ConvertProc describe 
objects owned by the manager. If the manager allocated any resources to produce the 
converted selection value, then a VaiueFreeProc must be returned with the Value so that 
the resources can be released. If a ValueCopyMoveProc was returned with the Value, after 
the converted selection value has been copied or moved, the manager must ensure that the 
correct things will happen when the Value's VaiueFreeProc is called (i.e., when the 
requestor calls Seiection.Free). This may involve replacing the original VaiueFreeProc. 

The manager's ConvertProc takes a zone that Selection guarantees is valid (e.xcept for the 
query operation). The manager should allocate any storage for the converted selection 
value from that zone. The ConvertProc can store the zone in the context (long unspecified) 
field of the Value record (or in a record pointed to by the context field). The VaiueFreeProc 
and ValueCopyMoveProc can then retrieve this zone to free the storage. 

Numerous defaults are provided by Selection to ease the manager's task of proper storage 
management. In practice, the ConvertProc can simply default the context field and 
Selection will place the zone there. Also, procedures such as FreeStd and FreeContext are 
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provided that perform the loopholes, free the storage, and store null and/or no-op values 
such as NopFree in the Value record. 

44.1.3.4 Storage Considerations for ManagerData 

The ManagerOata that identifies exactly what part of the manager's domain is currently 
selected should be allocated whenever a s«i«ction.Set is done and deallocated whenever 
ActOn [clear] is requested. In particular, a manager should not assume that there will be 
only one selection at a time in his domain. The existence of SaveAndSet and Restore and 
Encapsulate implies that the same manager code could have several pushed selections at 
once and therefore would have several ManagerOata records allocated at once. 

A manager that supports encapsulated or saved selections must carefully manage storage 
and access to the objects represented by the encapsulated selection. The saved selection 
case is slightly easier; the manager can assume that the ManagerOata will not be operated 
on unless it is the user's selection. When the saved selection is restored, the manager must 
make sure all the objects in the saved selection still exist. The encasulated case is 
somewhat harder. One approach is to save enough data about the selection to work 
properly if some of the objects disappear. For example, a folder application may normally 
maintain a selection as a span of objects: rows 1-5 are selected. To encapsulate the 
selection, the folder might have convert the selection into a list of fields so it can later 
access each file. Another approach (and the one used currently in the BWS) is to lock all of 
the objects in the encapsulated selection so that that user cannot modify them unto the 
requestor calls s«i«ction. 01 scard. 

44.2 Interface Items 

44.2.1 Requestor items 

44.2.1.1 Convert 

Convert: procedure [target: Target, zone: uncounted zone 4- nil] 
RETURNS [value: Value]; 

ConvertX: procedure [ 
target: Target, 
zone: uncounted zone 4- nil, 
manager: Saved 4> null Manager] 
returns [vaiue:Value]; 

Value: TYPE « record [value: long pointer, ...]; 

nuilValue: Value a [value: nil,. . .]; 

Convert is a request to the current selection manager to produce the selection as a type 
specified by target, if possible, value, value will be a long pointer to the converted selection. 
The TYPE of object pointed to by value, value depends on target and is described below under 
Target. If the conversion requires that storage be allocated, it will be allocated out of zone. 
If zone is defaulted, the system heap is used. 
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The value returned is read-only; it belongs to the manager. If the requestor wishes to (1) 
keep the value after it returns to the system, or (2) pass the value to another process, it 
must call Copy, Move, or CopyMove to make a copy of the value, which is then owned by 
the requestor. If Copy, Move, or CopyMove is called, the requestor must still call Free. 

If Copy, Move, or CopyMove is not called, the requestor must call Free after calling 
Convert. This allows the manager to free any resources that were allocated to perform the 
conversion. If Copy, Move, or CopyMove is called, the requestor then owns any resources 
and may retain them indeiiniteiy and/or may free them by calling Free. 

There are other fields in the Value record, but the requestor need not be cohcerned with 
them. They are described in the section on Manager Items 

nullValue is returned if the selection manager does not implement the desired conversion, 
or if the particular selection is incompatible with the target (e.g., Convert(integer] when 
non-numeric characters are selected). 

ConvertX adds an addition manager parameter to support encapsulated selections, 
manager is obtained by doing a Se<«ctionx. Encapsulate. If manager is defaulted, the 
operation applies the the global user's selection; otherwise the manager is called to convert 
the encapsulated selection represented by manager. ConvertX is exported by SeiectionX. 

Target: type • machine dependent{ 

window(O), shell, subwindow, string, length, position, 
integer, interpressMaster, file, fileType, token, help, 

interscript Script, interscriptFragment, serializedFile, name, firstFree, !ast(1777B)}; 
fiieWithFeedback:Target; 

Target describes the type of data to which a selection may be converted (see Convert). 
Modules that manage the current selection may choose not to implement conversion to 
some (or even most) of these types. The values described below are those stored in the value 
field of the S«lection.Value returned by Convert. fileWithFeedback is a target presently 
exported by SeiectionX. 

Special note for Targets that produce a stream.Handle: The strtam.Object pointed to by the 
Stream. Handle is read-only. Thus the requestor cannot even read the stream because that 
alters the stream state and thus the stream. Object. Before using the stream, the requestor 
must do a Copy, after which the ownership of the storage for the Stream.Object and any of its 
ancillary data moves to the requestor. Note also that the stream itself is read-only even 
after the Copy. The requestor should never attempt to write to the stream. After reading 
the stream, the requestor can free the stream and any associated resources by calling 
Stream.Oelete. Thus a typical stream requestor will do Convert[stream]; CopyH; <read 
stream >; stream. OeleteG; Note for selection managers: this last point means that the 
Stream.Oelete must be able to free any ancillary data associated with the stream. 

Note that some Target values refer to types that are not defined within the context of 
Viewpoint. Such targets so far include pieceLlst, help, interscriptScript, and 
interscriptFragment. Popular target types are included in the Selection interface as a 
convenience for clients. New target types will be put either into a SelectionExtras interface 
or, for little-used types, into private interfaces negotiated between managers and 
requestors and using Selection.UniqueTarget. The type associated with each Target is 
determined by system-wide convention. Several of these TYPE/Target conventions are 
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defined here. Other TYPE/Target conventions are documented elsewhere, see §44,2.2.8, 
UniqueTarget. 

Fine Point: This Selection interface is intended to support both XDE and ViewPoint clients, so there may be 
Targets that do not make sense in one domain or the other. Targets that only make sense in one domain show that 
domain in parentheses. 



window 



shell 



subwindow 



string 



length 
position 
pieceLlst 
integer 

interpressMaster 
file. 



fileWithFeedback 



yields a window.Handle for the window containing the 
selection. 

yields a StarWindowShell.Handle for the window containing the 
selection. (Viewpoint) 

yields a window.Handle for the subwindow containing the 
selection. (XDE) 

yields a lon<3 pointer to xstring.ReaderBody (an 
xstring. Reader) representing the text of the selection. If the 
current selection is too large, the manager of the selection 
may return nullValue when asked to convert to a string. The 
requestor should then ask to enumerate the selection as a 
sequence of smaller strings. Note: The requestor must copy 
the ReaderBody before altering it. 

yields a long pointer to long cardinal containing the length 
of the selection in characters. 

yields a long pointer to long cardinal containing the position 
within the source. 

yields a list of pieces, understood by the internals of XDE's 
PieceSource interface. (XDE) 

yields a LONG pointer to long integer containing the result of 
converting the contents of the selection to a number. 

yields a Straam.Handle onto an Interpress master, according 
to the Interpress standard. 

yields a long pointer to NSFiie.Reference for the file (if any) 
associated with the selection, e.g., the backing file for a Star 
document icon. When calling Copy, Move, or CopyMove, the 
data parameter must be a long pointer to NSFiie.Ref erence of 
the parent directory to where the file should be copied or 
moved. After calling Copy, the value. value is replaced by a 
LONG POINTER TO NSFile. Reference of the newly copied file. 
(Viewpoint) 

same as file but tells the manager's CopyMoveProc to post 
the names of the objects to the attention window as they are 
copied or moved. (Viewpoint) 
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fiieType 



token 



heip 



yields a LONG POINTER TO NSFile.Type for the file (if any) 
associated with the selection. (Viewpoint) 

yields a LONG POINTER TO xstring.ReaderBody (an 
xstrimi. Reader) that contains the first token of the current 
selection. Note: The requestor must copy the ReaderBody 
before altering it. 

yields a long pointer to a value or data structure that 
specifies what should happen if the help key is pressed. 
Consult the Help documentation (not in this manual) for the 
exact TYPE. 



interscriptScript 



i nterscri ptFragment 



3rields a Str«am.Handle onto a complete script, according to 
the Interscript standard. It begins with the "Interscript I.O . . 
and is in machine code. 

yields a Stream.Handle onto a single Interscript node, in 
machine code. 



serializedFile 



name 



firstFree 



A Target of serializedFile results in a Stream.Handle. 
Str«am.GetXXX opierations can be performed on the stream. 
This is useful for retrieving files from non-NSFile mediums 
such as a floppy disk. 

A Target of name results in a xstring.Reader that contains 
the name of the object. 

is used internally by UniqueTarget and should not be used 
by clients. 



ConvertNumber: procedure [target: Target] 
RETURNS [ok: BOOLEAN, number: long UNSPsaFiEO]; 



This procedure lets the requestor streamline his code in many cases. ConvertNumber calls 
Convert and assumes that the resulting value. value references a 32-bit object. (This is true 
of the targets length, position, integer, and fiieType, and may also be true of targets 
defined using UniqueTarget.) The object is returned as number, and the Value is then 
freed (S«l«ction.Free). If the selection manager does not support the desired conversion (that 
is» it returns nullVaiue), or if the selection could not be converted to a number, 
ConvertNumber returns ok:FALSE; otherwise, it returns ok:TRUE. 



Free: procedure [v: ValueHandle]; 
VaiueHandle: TYPE ■ long pointer to Value; 



Free allows the manager to free any storage associated with v. Free should always be 
called after calling Convert (but if Copy or Move is going to be called, don't call Free until 
after calling Copy or Move). Fine point: after calling Copy or Move, Free is a no-op since 
the manager should have handed over any storage ownership to the requestor, but it is 
easier for the requestor to simply remember the rule, ** Always call Free." The manager 
will take care of ensuring that an extraneous Free is harmless. 
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44.2.1.2 Query 

A requestor can determine exactly which Targets the current selection can be converted to 
and how difHcult the conversion would be. The most common way to do this is 
CanYouConvert, which takes a Target and returns a boolean indicating whether the 
selection can be converted to that Target. HowHard is similar to CanYouConvert but 
returns a Difficulty. Query allows a requestor to determine the Difficulty of conversion for 
an ARRAY of Targets. 

Note: For all these queries, the manager is indicating how hard it would be to attempt to 
convert the selection to that target type. Attempt is a key word. The manager might be 
willing to attempt to convert the selection to an Interpress master and yet run out of disk 
space when the conversion is actually requested. Likewise, the manager might support 
conversion to integer, but the conversion could still fail if the selection contains invalid 
characters. 

Can YouCon vert: procedure [target: Target, enumeration : boolean false] 
RETURNS [yes: boolean] ■ inline { 

RETURN [ HowHard [ target, enumeration ] # impossible ] }; 

CanYouConvertX: procedure [ 
target:Target, 

enumeration : boolean 4> false, 
manager: Saved 4- null Manager] 
RETURNS [yes: boolean] ■ inune{ 

return( HowHardX[ target, enumeration, manager ] # impossible] }; 

CanYouConvert determines whether the selection manager supports conversions to the 
specified target, enumeration « true means the requestor wants to know if the manager 
supports enumerating the selection in the specified target form. (See the section on 
Enumeration below.) CanYouConvertX is the same procedure but can operate on an 
encapsulated selection manager. If manager is defaulted, the operation uses the default 
global selection. CanYouConvertX is exported by SelectionX. 

HowHard: procedure [target: Target, enumeration: boolean false] 
returns [difficulty: Difficulty]; 

HowHardX: procedure [ 
target:Target, 

enumeration: boolean 4- false, 
manager: Saved *- null Manager] 
RETURNS [difficulty: Difficulty]; 

Difficulty: type ■ {easy, moderate, hard, impossible}; 

HowHard determines the difficulty the selection manager would have attempting to 
convert to the specified target, enumeration ■ true means the requestor wants to know 
the difficulty of enumerating the selection in the specified target form. (See the section on 
Enumeration below.) HowHardX is the same procedure but can operate on an 
encapsulated selection manager. If manager is defaulted, the operation uses the default 
global selection. HowHardX is exported by SelectionX. 
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The difficulty ratings are interpreted roughly as follows 
easy 



moderate 
hard 

impossible 



Requires virtually no computation (other than allocating 
storage for the Value). Example: length when the selection 
is being maintained as two character indices within a 
string. 

Requires some amount of computation but nothing 
outrageously time-consuming. Example: converting the 
above-mentioned substring representation to a string or 
integer target. 

Requires extensive computation. Example: 
interpressMaster. 

The selection manager does not support this conversion. 



Query: procedure [targets: long descriptor for array opQueryElement]; 

QueryX: procedure [ 

targets: long descriptor for array of Query Eiement, 
manager: Saved null Manager]; 



QueryEiement: type « record ( 
target: Target, 

enumeration: BOOLEAN 4- FALSE, 
difficulty: Difficulty trash]; 

Query allows a requestor to determine the difficulty of conversion for several Targets. The 
requestor should construct the array of QueryEiement, filling in target and enumeration 
for each QueryEiement. The manager will then store a Difficulty in each QueryEiement 
indicating how hard it would be to attempt to convert the selection to that target. The 
requestor can then examine the difficulty field of each QueryEiement after the call to 
Query. QueryX is the same procedure but can operate on an encapsulated selection 
manager: If manager is defaulted, the operation uses the default global selection. QueryX 
is exported by SelectionX. 

44.2.1.3 Enumeration 



The selection is sometimes a collection of items (for example, several rows of a folder) or a 
single large item that can be split up (for example, a long string can be broken into several 
smaller ones). A requestor can request that each item or part of such selections be 
converted to some Target by calling s«i«ction.Enumerate. Enumerate is logically similar to 
calling Convert for each item and the same storage ownership rules apply (see Convert). 
Not all selection managers support enumerating the selection; for example, they do not 
support a selection that is more than one item. Often a requestor will call Convert and if 
that fails (returns nullValue), call Enumerate. 

Enumerate: procedure [ 

proc: EnumerationProc, target: Target, data: RequestorData 4- nil, 
zone: uncounted zone «- nil] 
returns [aborted: boolean]; 



44-11 



44 



Selection 



EnumerateX: PROCEDURE [ 
proc: EnumerationProc, target: Target, data: RequestorOata nil, 
zone: uncounted zone nil, 
manager: Saved null Manager] 
RETURNS [aborted: boolean]; 

EnumerationProc: type ■ procedure [element: Value, data: RequestorOata] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

RequestorOata: TYPE ■ long pointer; 

Enumerate is a request to the selection manager to enumerate the current selection, 
converting each element to target, proc is called for- each element, data is passed back to 
proc each time it is called. As with the Value returned by Convert, the requestor must 
consider each element to be read-only until Copy, Move, or CopyMove is called, and the 
requestor must free the value by calling Free for each element. Free allows the manager 
to free any storage associated with element. Free should always be called for each element 
(but if Copy or Move is going to be called, don't call Free until after calling Copy or Move). 
Fine point: after calling Copy or Move, Free is a no-op since the manager should have 
handed over any storage ownership to the requestor, but it is easier for the requestor to 
simply remember the rule, ''Always call Free." The manager will take care of ensuring 
that an extraneous Free is harmless. 

stop is returned from proc by the requestor and indicates whether the enumeration should 
be stopped, aborted indicates whether the enumeration completed normally or terminated 
prematurely. 

If the manager cannot convert the selection to the target type or Lf the manager does not 
implement enumeration, proc will not be called. 

EnumerateX is the same procedure but can operate on an encapsulated selection manager. 
If manager is defaulted, the operation uses the default global selection. EnumerateX is 
exported by SelectionX. 

Warning: the requestor must not do anything Inside of proc that would cause Selection to 
be called (Clear, for example) since this will result in a monitor lock. 

Reconversion: signal [ 
target: Target, zone: uncounted zone] returns [Value]; 

ReconvertDuringEnumerate: procedure [ 
target: Target, zone: uncounted zone nil] returns [Value]; 

A requestor may wish to reconvert the current item during an enumeration of the 
selection. The requestor should call ReconvertOuringEnumerate, which will raise the 
signal Reconversion. If the manager supports reconversion, it should catch the signal and 
return the reconverted value. If the manager does not support reconversion, it should 
ignore the signal. Enumerate will catch the signal and return nullValue. 
ReconvertOuringEnumerate acts like Convert with respect to zone. 

maxString Length: cardinal ■ . . . ; 
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maxStringLength is obsolete. 

44.2.1.4 Copy, Move, Free, etc. 

The Values produced by Convert and Enumerate are strictly read-only. The storage is 
owned by the manager. The requestor may examine the data referenced by the value field 
but must not alter it. 

If the requestor wishes to (1) keep the value past when it returns to the system, or (2) pass 
the value to another process, it must call Copy, Move, or CopyMove. These in turn invoke 
a procedure supplied by the selection manager that modifies the Value such that the 
requestor may then make changes to value.valuef without affecting the selection 
manager. Fine Point: This procedure is returned by the manager as part of tlie Value record, but the requestor 
never needs to know about these details. If a Move is performed, the item is also deleted from the 
manager's domain. After the Move or Copy, any storage associated with the Value is now 
owned by the requestor. This storage may be freed by calling Free. 

For example, if the current selection is a document icon, then Convert[file] yields a Value 
containing a long pointer to NSFHe.Reference for the file containing the document. If the 
requestor were to create a new document and associate it with the same file, it would 
probably have undesirable effects. Instead, the requestor should call Copy, giving it a long 
pointer to NSFila.Reference for the destination directory of the new file. When Copy returns, 
the Value contains a reference to a copy of the original file, and the requestor can use this 
freely. Furthermore, whereas calling Free with the original Value might have deleted the 
file (since the file then belonged to the manager, who might have created it solely for the 
Convert request), calling Free for the new Value frees only the NSFUe.Reference storage 
(since the file is now a permanent object belonging to the requestor). 

Copy: PROCEDURE [v: VaiueHandle, data: long pointer] * inline { 
CopyMove[v, copy, data]}; 

Move: procedure [v: VaiueHandle, data: long pointer] ■ inune { 
CopyMove[v, move, data]}; 

CopyMove: ValueCopyMoveProc; 

ValueCopyMoveProc: type • procedure [ 

v: ValueHandle, op: CopyOrMove, data: long pointer]; 

CopyOrMove: type ■ {copy, move}; 

Copy, Move, and CopyMove request the manager to make a copy of the converted selection 
value (v.value f ) and, for Move, also delete the selection from the manager's domain. A 
requestor may call these procedures after calling Convert or from an EnumerationProc 
while doing an Enumerate, data will be passed to the manager; what it points to depends 
on the particular Target, data often points to a destination container for the copied value. 
For example, for Target file, data is a long pointer to NSFHe.Reference for the destination 
directory. The exact meaning of data for each target is specified in the description of that 
target under Target above. Copy, Move, and CopyMove may raise Error 
[I n valldOperation] . 



44-13 



Selection 



Encapsulated selections also work with Copy and Move: if a requestor has an encapsulated jiflli 
selection and obtains a value with ConvertX or EnumerateX, they can use all of the 
standard operations that work with a Value. 

44.2.2 Manager Items 

44.2.2.1 Set 

Set: PROCEDURE [pointer: ManagerOata, conversion: ConvertProc, actOn: ActOnProc]; 
ManagerOata: type « long pointer; 

The Set procedure allows a client to become the manager of the current selection by 
supplying the Selection interface with a pair of procedures. The ActOnProc is called to 
modify or manipulate the current selection. The ConvertProc is called to get the value of 
the current selection. The value of pointer passed to Set is used as the data argument in 
calls to conversion or actOn. pointer typically points to a record that describes what part of 
the manager's domain is currently selected. If there is already a selection manager when 
Set is called. Set first calls that manager with ActOn[unmark] and ActOn[ciear]. Set 
automatically calls the new ActOnProc with an action of mark. 

Either conversion or actOn can be explicitly nil. If conversion is nil, then Convert always 
returns nullVaiue, Enumerate is a no-op, and Query will always respond impossible. If 
actOn is nil, then ActOn is a a no-op for all actions. ^/n^ 

ConvertProc: type ■ procedure [ 
data: ManagerOata, 
target: Target, 
zone: UNCOUNTED zone, 
info: Conversion! nfo <- [convertQ] ] 
RETURNS [value: Value]; 

Conversioninfo: TYPE a record [select type: * from 
convert * > null, 

enumeration « > [proc: procedure [Value] returns [stop: boolean]], 
query « > [query: long descriptor for array of QueryElement], 
enocase]; 

A ConvertProc is provided by a manager when becoming the manager; that is, when 
calling Set or SaveAndSet. The manager's ConvertProc is called when a requestor calls 
Convert, Enumerate, or Query. The ConvertProc should perform the conversion, the 
enumeration, or the query, info is a variant record indicating which operation to perform; 
it contains data appropriate to each operation. The ConvertProc should use with info select 
to determine which operation is requested. Each operation is described in detail in the 
following sections, data is the pointer that was passed to Set or SaveAndSet and typically 
points to a record that describes what part of the manager's domain is currently selected, 
target indicates the type of object that the selection should be converted to and is 
meaningful only for conversion and enumeration, zone should be used to allocate any iiH^ 
storage for the converted selection value and is meaningful only for conversion and 
enumeration. 
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ActOnProc: type a procedure [data: ManagerOata, action: Action] 
RETURNS [cleared: boolean false]; ' 

An ActOnProc is provided by the manager of the selection to perform various actions on the 
selection. ActOnProc is fully described later in this chapter. 

44.2.2.2 Conversion 

Conversionlnfo: TYPE ■ record [select type: * from 
convert a > nuu, 

enocaseJ; 

Value: type ■ record [ 
value: long pointer, 

ops: LONG POINTER TO ValuePrOCS 4- NIL, 

context: long unspegfied 4-0]; 

Convert calls the manager's ConvertProc with convert Conversionlnfo to perform the 
requested conversion. The ConvertProc returns a value: Value. If the conversion can be 
performed, value.value should point to the converted selection value; vaiue.ops should 
point to a pair of procedures, a ValueFreeProc that will release any resources that were 
allocated to perform the conversion and a VaiueCopyMoveProc that will copy or move the 
converted value; value.context can be used to save any information that the pair of 
procedures might need, vaiue.ops and value.context are described in much more detail 
later. If the manager does not support the requested Target or there is some problem with 
the conversion, the ConvertProc should return nullValue. See Target for the effect of 
different conversion targets. 

If the conversion requires that an object be allocated, the ConvertProc should allocate it out 
of zone. If the requestor passed a nil zone to Convert, Convert passes the system zone to 
ConvertProc The ConvertProc can assume that it is always given a valid zone. 

44.2.2.3 Query 

Conversionlnfo: TYPE « record [select type: *from 
• • »» 

query « > [query: long descriptor for array OP Query£lement], 
endcase]; 

QueryElement: type « record [ 
target: Target, 

enumeration: boolean <- false, 
difficulty: Difficulty trash]; 

Query, HowHard, and CanVouConvert call the manager's ConvertProc with query 
Conversionlnfo. The ConvertProc should examine the target and enumeration fields of 
each Query£lement (these were filled in by the requestor) and fill in the difficulty field 
indicating how hard it would be to attempt to convert the selection to that target 
(enumeration * false) or to convert the selection to an enumeration of that target 
(enumeration a true). 
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All managers are expected to implement queries; the assumption is that most di^culty 
ratings can be determined simply by indexing into a constant array. The Value actually 
returned by the ConvertPrbc in response to a query is ignored; nullVaiue or trash may be 
returned. 

Note that the manager is indicating how hard it would be to attempt to convert the 
selection to that target type. Attempt is a key word. The manager might be willing to 
attempt to convert the selection to an Interpress master, and yet run out of disk space when 
the conversion is actually requested. Likewise, the manager might support conversion to 
integer, but the conversion could still fail if the selection contains invalid characters. 

44.2.2.4 Enumeration 

Conversioninfo: type « record [select type: * from 

• • • » 

enumeration ■ > (proc: procedure [Value] returns [stop: boolean]]* 

• • • I 

enocase); 

Enumerate calls the manager's ConvertProc with enumeration Conversioninfo. The 
ConvertProc should convert each element or part of the selection according to target and 
call proc for each element. The Value passed to proc is just as it is for conversion (see the 
section on Conversion above and the following section). If proc returns stop » true, the 
ConvertProc should stop the enumeration and return. The Value returned by the 
ConvertProc after an enumeration is ignored; nullValue or trash may be returned. Not ail 
selection owners are expected to implement enumerations; if an enumeration is requested 
and not supported, the ConvertProc should simply return and take no other action. Fine 
Point: The ConvertProc does not call the requestor's EnumerationProc directly; rather, proc is inside Enumerate 
and Enumerate calls the requestor's EnumerationProc. This lets Enumerate insert the zone into the Value.context 
if it is zero, just as Convert does for Values produced by a simple conversion. 

maxStringLength: cardinal ■ . . . ; 

maxStringLength is obsolete. 

44.2.2.3 Free, Copy, Move, etc. 

ValueHandle: TYPE ■ long pointer to Value; 

Value: type ■ record [ 
value: long pointer, 
ops: long pointer to ValueProcs «- nil, 
context: long unspecified ^0]; 

The selection manager provides the value of the selection, or other selection- related 
information, to the requestor by means of Value records. These records are typically either 
returned by a ConvertProc or passed as elements to the requestor's EnumerationProc. The 
ops field defines the effect of Free, Copy, Move, and CopyMove. The context field may be 
used to store data for use by the ops procedures. If the context field is defaulted (zero) by 
the selection manager. Selection stores the zone that was passed to the ConvertProc there 
before the Value is handed to the requestor. 
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ValueProcs: type ■ record [ 
free: ValueFreeProc «- nil, 
copyMove: VaiueCopyMoveProc *- nil]; 

ValueProcs are returned by the manager as part of a Value record. If the manager allocated 
any resources to produce the converted selection value, then a ValueFreeProc must be 
returned with the Value so that the resources can be released, free is called when the 
requestor calls Free. If the converted selection value can be copied or moved, the manager 
must return a VaiueCopyMoveProc with the Value. For example. Targets string and file 
can be moved or copied, while it does not make sense to move or copy Targets window and 
fileType. copyMove will be called when the requestor calls Copy, Move, or CopyMove. 

44.2.2.5.1 Free 

ValueFreeProc: type » procedure [v: ValueHandle]; 

If any resources were allocated to produce the converted selection value, they should be 
released in the manager's ValueFreeProc. The ValueFreeProc is returned as part of the ops 
field of a Value. The ValueFreeProc will be called when the requestor calls Free, v points to 
the Value that represents the converted selection. 

Defaults are provided such that for the most common case when the ConvertProc simply 
allocates one node of storage from the passed zone, the manager need not supply a 
ValueFreeProc. Selection takes care of freeing the storage when the requestor calls Free. 
The details of how this works are as follows: 

The manager's ConvertProc takes a zone that Selection guarantees is valid. The manager 
should allocate any storage for the converted selection value from that zone. The 
ConvertProc can store the zone in the context field of the Value record (or in a record 
pointed to by the context field); then the ValueFreeProc can retrieve this zone to free the 
storage. Selection stores this zone in the context field if context is zero (the default) in the 
Value returned by the ConvertProc (or passed to the EnumerationProc). v.value points at 
the converted selection object to be freed. Now, Free calls FreeStd if the Value passed to 
Free has ops ■ nil or ops.free ■ nil. FreeStd treats v.context as a zone and calls 
v.context.FREE(@v.value]. 

If there are in fact no resources that should be freed (for example, after Convert[windowl), 
the selection manager should use NopFree as the ValueFreeProc. (See also 
nopFreeVal ueProcs.) 

FreeStd: ValueFreeProc; 

FreeStd assumes the resources of the Value can be freed by treating v.context as a zone and 
calling v.context.FREE(@v.value]. If a Value has ops • nil or ops.free « nil. Free will call 
FreeStd. 

NopFree: ValueFreeProc; 

The NopFree procedure should be used as the ops.free for a Value involving no temporary 
resources owned by the selection manager. Thus, a Value created by Convert[window] 
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would probably use NopFree, as would Convert[string] if the Value.vaiue pointed to a 
permanent xstring. Reader Body belonging to the manager.(See also nopFreeVaiueProcs.) 

44.2^5^ Copy and Move 

ValueCopyMoveProc: type « procedure ( 

v: ValueHandle, op: CopyOrMove, data: long pointer]; 

CopyOrMove: type ■ {copy, move}; 

The manager's ValueCopyMoveProc is called to copy or move the converted selection 
value. A ValueCopyMoveProc is returned by the manager's ConvertProc as part of the ops 
field of a Value. The ValueCopyMoveProc is called when the requestor calls Copy, Move, or 
CopyMove. The ValueCopyMoveProc should modify the Value such that it no longer 
involves any manager-owned storage. If a Move is performed, the item is also deleted from 
the manager's domain. (Some managers may implement Copy but raise 
Error[invalidOperation] if asked to do a Move.) data is the data parameter that the 
requestor passed to copy or move. It is often a pointer to the destination container for the 
copied value. The interpretation of data depends on the Target; it is specified in the 
description of each target under Target above, v points to the Value representing the 
converted selection, op indicates whether to do a copy or move. Note: v.context can be used 
by the manager to save information between the ConvertProc and the 
ValueCopyMoveProc. 

The ValueCopyMoveProc should release (or perhaps simply turn over control of) any 
resources that were allocated by the ConvertProc to produce the original converted value. 
Conceptually, the ValueCopyMoveProc makes a copy of the converted value, then releases 
any resources that were used to produce the original converted value. If the original 
converted value itself was a copy produced by the conversion procesis, this effect might be 
achieved by doing nothing — the requestor just becomes the owner of the copy. 

If the converted value can only be copied once (the typical case), the ValueCopyMoveProc 
should also set v.ops.copyMove to nil to prevent the manager's ValueCopyMoveProc from 
being called again. If the requestor does call Copy or Move again. Selection raises Error 
[invalldOperation]. 

The ValueCopyMoveProc should also ensure that v.ops.free and v.context have 
appropriate values so that when the requestor calls Free, the right thing happens. For 
example, if the newly copied selection was allocated from a zone, v.ops.free should free it 
Scorn that zone (see ValueFreeProc and FreeStd); or if the newly copied selection has no 
storage allocated for it, v.ops.f ree should be NopFree. 

nopFreeVaiueProcs: readonly long pointer to ValueProcs; - @[NopFree, nil] 

This is provided for use as the ops vector in Values that require no temporary storage and 
that cannot be moved or copied. The window and subwindow Targets typically produce 
such values. 

FreeContext: procedure [v: ValueHandle, zone: uncounted zone] « inline { 

ZOne.FREE[L00PH0LE{@V.C0ntext. LONG POINTER TO LONG POINTER]]; 

V.context 4- LOOPHOLE(zone]}; 
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When the requestor calls Copy or Move, the manager's ValueCopyMoveProc is expected to 
modify the Value that it no longer involves any manager-owned storage. If the manager 
has been using the context field as a pointer to additional private data, this private data 
must be freed. This would normally require merely a zone.FREE(@v.context]; however, 
since the context is a long unspecified, a loophole is needed. FreeContext hides this 
LOOPHOLE from the impiementor and does the required zone.FREE. It also stores the zone in 
place of v.context, for possible later use by FreeStd. 



44.2.2.6 ActOn 

ActOnProc: type ■ procedure [data: ManagerOata, action: Action] 
RETURNS [cleared: boolean false]; 

An ActOnProc is provided by the manager of the selection to perform various actions on the 
selection, data is the pointer that was passed to Set or SiveAndSet and typically points to a 
record that describes what part of the manager's domain is currently selected, action 
indicates what action to perform (see Action below). An ActOnProc should return cleared: 
TRUE if the action resulted in the selection being cleared; that is, the manager is no longer 
responsible for the selection. (This should always be the case for action: clear and may also 
occur for delete or clearifHasinsert.) clear should also be set for encapsulate to let Selection 
know that the manager actually supports encapsulate. 



Action: TYPE a MACHINE 0EPEN0ENT{ 

clear(0), mark, unmark, delete, clearifHasinsert, save, restore, f irstFree, last(255)}; 
encapsulate: Action; 
encapsulate is exported by SelectionX. 



clear 
mark 
unmark 
delete 

clearifHasinsert 



unselects the current selection by freeing any associated 
private data, undoing TIP notification changes, etc. 

highlights the current selection. If the selection is already 
highlighted, this is a no-op. 



dehighlights the current selection, 
already highlighted, this is a no-op. 



If the selection is not 



deletes the contents of the current selection. The selection 
manager may decide against actually deleting it. 

same as unmark plus clear, but only if the insertion point 
(input focus) is in the selection. This action is used when a 
secondary selection has been completed (for copy- from); if 
the place to which the secondary selection is to be copied 
(the insertion point) is within the selection itself, the 
selection is cleared after obtaining its contents and before 
the insertion takes place. 



save unselects the current selection, but does not necessarily free 

any associated private data, because the selection is 
expected to be restored later. This action will often be a no- 
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restore 
encapsulate 



op, but the manager might need to undo a special TIP 
notifler, for example. 

restores a previously saved selection. 

much like save, unselects the current selection but does not 
clear it. Always proceeded by an unmark. The manager is 
expected to do whatever is necessary to allow the selection to 
be operated on from the background. This may involve 
changing the manager data structure so that the manager 
procs can know that they are operating on an encapsulated 
selection. The manager may also lock objects down by 
making them "busy" or otherwise prevent them from being 
operated on while they are encapsulated. The manager 
must set clear to TRUE to indicate that the encapsulate 
completed successfully. See §44.2.2.7 for more discussion of 
encapsulated selections, encapsulate is exported by 
SeiectionX. 



firstFree 



is used internally by UniqueAction and should not be used 
by clients. 



Observe that, contrary to the interpretations used in the XDE Selection interface, the clear 
action does not dehighiight the selection. S«iection.Clear (usually) does an explicit unmark 
before clearing the selection. Likewise, save does not imply unmark, nor does restore imply 
mark. This lets a client choose to leave a primary selection highlighted while a secondary 
selection is being made. 



44.2.2.7 Save and Restore, Encapsulated selections 

SaveAndSet: procedure [ 

pointer: ManagerOata, conversion: ConvertProc, actOn: ActOnProc, 
unmark: boolean 4- true] 
RETURNS [old: Saved]; 

SaveAndSet is the same as S«i«ction.Set except that the existing selection, if any, is told to 
ActOn[save] rather than ActOn(clear]. That is, the existing selection is expected to retain 
any private state so that it can later be restored via Selection. Restore. If it subsequently 
turns out that the saved selection is never going to be restored, it should be given to 
S«l4Ktion.0iscard so that the former selection manager will have a chance to discard any 
associated private data. A saved selection must always be given eventually to either 
Restore or Discard; furthermore, once that has been done, the Seiection.Saved must not be 
used for anything else. 

It is perfectly acceptable to call SaveAndSet when there is no selection. If the resulting 
s«lection.Saved is passed to Seiection.Restore, it acts like Setection.Clear. Also, unlike for Clear, 
ClearOnMatch, and Restore, it is quite reasonable to call SaveAndSet with unmark: false, 
thereby requesting that the saved selection remain highlighted while a secondary selection 
is performed. If this is done, the caller will usually wish to specify mark: false when the 
saved selection is restored. Note: Calling SaveAndSet with unmark: false does not 
necessarily mean that the old selection is marked. The selection manager, or some other 
client, might have unmarked it. The present caller is simply saying, "Do not change the 



44-20 



Viewpoint Programmer's Manual 



44 



highlighting on my account,'* but has no way of knowing whether the saved selection is in 
fact highlighted. That is why it is always up to the selection manager to decide whether 
ActOn[mark] or ActOn(unmark] is a no-op. 

Encapsulate: procedure returns [Saved]; 

An encapsulated selection is much like a saved selection that can be operated on from 
outside the notifier process. Calling this procedure tells the selection manager to 
encapsulate the current selection and return it so it can be operated on at a later time. 
Calling Encapsulate clears the user's selection; the implementation calls ActOn[unmark] 
followed by Actonfencapsulate]. If the selection manager does not support the encapsulate 
action. Encapsulate will raise ErrorCoperationFaiied]. An encapsulated selection may be 
passed to any of the standard requestor operations that have the eextra manager 
parameter: ConvertX, EnumerateX, and so forth. An encapsulated selection must always 
be cleared with Discard. A requestor calling Encapsulate should be aware that the 
encapsulated selection may be locked to prevent the user from operating on those objects; 
the requestor should not hold an encapsulated selection for any longer than necessary. 
Encapsulate is exported by SelectionX. 

Saved: type [6]; 

Objects of this type are created by s«i«ction.SaveAndSet and s«l«ctionx.Encapsuiate to 
encapsulate a selection that is to be restored later (SaveAndSet) or operated on from 
another process (Encapsulate). It is opaque to prevent requestors from invoking the 
manager directly. 

Restore: procedure [saved: Saved, mark, unmark: boolean 4-true]; 

This procedure re-institutes a previously saved selection as the current manager. The 
existing selection, if any, is requested to ActOn(unmark] (unless unmark is false; see 
Selection. Clear) and then ActOn[clear]. The selection being restored is asked to 
ActOn[restore] and then ActOn[mark] (unless mark is false). 

Discard: procedure [saved: Saved, unmark: boolean 4-true]; 

If a client, having saved somebody else's selection (see SaveAndSet), determines that it 
should never be restored, he should call this procedure to free the associated resources. The 
current selection is not affected. The ActOnProc of the saved selection is called with action: 
unmark (unless unmark is false; see Clear) and again with action: clear. Thus the 
ActOnProc must be prepared to handle these operations vvhile the corresponding selection 
is saved. Callers of Encapsulate must call Discard to free the encapsulated selection. The 
ActOnProc is not called to unmark the selection in this case because Encapsulate always 
unmarks the selection first. 

44^2.8 Miscellaneous 

On all of the procedures below, use unmark: false only if you know the area of the screen 
containing the selection is going to be repainted soon anyway; for example, if the window is 
going away. 

Clear: procedure [unmark: boolean 4-true]; 
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The Clear procedure requests that the current selection be cleared. It is equivalent to 
calling ActOn{clear], preceded by ActOn(unmark] if unmark is true. The only time unmark 
should be false is if the caller knows the area of the screen containing the selection is going 
to be repainted soon anyway; for example, if the window containing the selection is going 
away. 

ClearOnMatch: procedure [pointer: ManagerOata, unmark: boolean 4>true]; 

It is sometimes difficult to determine if you are the manager of the current selection. The 
CearOnMatch procedure is the same as Clear except that no action is taken unless pointer 
matches the ManagerOata of the current selection. ClearOnMatch is equivalent to if 
s«i«ction.Match(pointer] then s«i«ctjon.CIear[unmark]. 

ActOn: procedure [action: Action]; 

The ActOn procedure communicates a request for an action to the manager of the current 
selection. (See also UniqueAction.) Calling ActOn[ciear] is not recommended, since there 
would be a tendency to forget to unmark first. Use Selection.Clear instead. 

Match: procedure [pointer: ManagerOata] returns [match: boolean]; 

This procedure returns true if the caller is the current selection manager, which is 
assumed to be the case if and only if pointer is equal to the ManagerOata associated with 
the current selection (as specified by Set, SaveAndSet, or Restore). Note: A selection 
manager may opt to have nil as the ManagerOata. In this case, the manager should not use 
Match since it would not be able to distinguish itself from other managers using nil. 
However, Match[NiL] always returns false if there is no selection; that is, after 
SeiectionXlear. 

UniqueTarget: procedure returns [Target]; 

The UniqueTarget procedure allows a client to define its own private conversion type. It 
returns a new Target in [firstFree.Jast]. May raise Error [tooMany Targets]. The use of 
private target types severely limits the exchange of Information between applications and 
should be avoided if possible. 

UniqueAction: procedure returns [Action]; 

The UniqueAction procedure allows an application to de^e its own private operations on 
the selection. It returns a new Action in [firstFree..last]. May raise Error 
[tooManyActions]. 

44.2.3 Errors 

Error: error [code: ErrorCode]; 

ErrorCode: type ■ { 

tooManyActions, tooManyTargets, invaiidOperation, 
operationFailed, didntAbort, didntClear}; 



tooManyActions may be raised by UniqueAction. 
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tooManyTargets may be raised by UniqueTarget. 

invaiidOperation raised if Copy or Move is called with a Value tliat does not 
implement the operation. 

operationFailed may be raised by a VaiueCopyMoveProc if the operation is 
permitted but nevertheless fails, for example due to an NSFiie error. 

didntAbort and didntClear are never raised. 
44.3 Usage/Examples 

44.3.1 What Selection Is NOT 

The trash bin and insertion features of the Mesa interface are not supported. If they are 
needed, a separate (smaller) interface should be created for them, as they do not really 
require the generality available for actual selections. 

44.3.2 Examples of Storage Allocation for Manager's ConvertProc 

Here the various storage allocation cases are discussed that arise, depending on Target, 
how the selection is maintained by the manager, etc. 

• Simplest case: no storage associated with this Target, no copy/move. 

• Example: selection is a string in a window and Target ■ window. 

• Manager's ConvertProc should have: 

RETURN [ [value: window, ops: s«ie€tion.nopFreeVaiueProcs] ] 

There is nothing allocated, nothing to free, so ops.f ree is S«lection.NopFree. It makes no 
sense to copy or move a window this way, so ops.copyMove is nil. 

• Slightly more complex case: no storage associated with this Target, allow copy/move. 

• Example: selection is a piece of a larger backing string and is maintained as an 
xstring.ReaderBody and Target ■ string. 

• Manager's global frame: 

myValueProcs: Selection. ValueProcs <- [ 

free: Seiecticn-NopFree, copy Move: CopyMoveString ]; 
SelectlonOata: type ■ record [ substring: xstring.ReaderBody,... ]; 
~ substring points at the same bytes as the backing string 

• Manager's ConvertProc: 

OPEN seiectionOata: narrow [data, long pointer to SeiectionOata]; 
RETURN [ [value: @selectionOata.substring, ops: @my ValueProcs] ]; 
— Selection will put zone into the context field. 
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Here the requestor points directly at the SeiectionOata.substring. The value. value f 
cannot be changed by the requestor until after the CopyMoveString is called. 

• Manager's CopyMoveString: 

V. value «- xstring.CopyReader [r: narrow [v. value, xstring.Reader], 

z: NARROW [v.context, uncounted zone] ]; 
v.ops.free4-NiL; 

After doing the copy, v.ops.free is replaced with nil, which causes Free to call FreeStd, 
which frees the copied ReaderBody and bytes. Note: CopyReader allocates both the 
ReaderBody and the bytes from a single allocation unit. 

Note: The storage for the SelectionOata is allocated when he s«iection.Set Is done and 
deallocated when ActOn [clear] is called. 

• Tsrpical case: some storage associated with this Target, allow copy/move 

• Example: selection is a piece of a larger backing string and is maintained as an 
Environin«nt.Bloci< and Target « String. 

• Manager's global frame: 

myValueProcs: s«iection.\/aiueProcs *- [ free: nil. copyMove: CopyMoveString ]; 
SelectionOata: type « record [ block: Environment-Block,... ]; 

- block represents the seiection. 

- block.pointer points to the backing string. 

• Manager's ConvertProc: 

OPEN SelectionOata: narrow [data, long pointer to SelectionOata]; 

RETURN [ [ 

value: zone.NEw[xstring. ReaderBody 

xstring.FromBlock [selectionOata.block], 
ops: @myValueProcs] ]; 
— Seiection wili put zone into the context field. 
" ops.f ree ■ nil means that FreeStd wiil be called. 

Here we allocate a ReaderBody that points directly into our backing string. Free will call 
FreeStd, which will free the ReaderBody. 

• Manager's CopyMoveString: 

OPEN zone: narrow [v.context, uncounted zone] ; 
OPEN selectionSubstring: narrow [v.vatue, xstring. Reader] ; 
v.value «- xstring.CopyReader [ selectionSubstring, zone ]; 
zone.FREE [ ©selectionSubstring ]; - frees the ReaderBody 

CopyReader copies both the ReaderBody and the bytes. After doing the copy, we free the 
ReaderBody. Note: After the copy. Free will still call FreeStd, which will free the copied 
ReaderBody and bytes. 
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44.3.3 Detailed Flowchart of a Selection. Convert 

Following is the exact sequence of events that takes place in performing a Sei«ction.Convert, 
showing what the requestor does, what the manager does, and what Selection does. 
Various storage allocation cases arise, depending on the Target, what the requestor wants 
to do, etcMost of the cases are covered here. This will be most useful to managers, but 
anyone desiring an overall understanding of Selection will benefit from following these 
details. 

• Requestor calls Saiection.Convert. 

• Convert calls the manager's ConvertProc. If the requestor provided a nil zone, Convert 
passes H«ap.systemZone. 

• Manager constructs a Value, potentially allocating storage for value. value f and/or for 
vaiue.context f . value.ops may or may not be provided, depending on the selection 
Target and the manager. Manager returns value to Convert. 

• If vaiue.context is defaulted. Convert puts zone into vaiue.context and returns to 
requestor. 

• If requestor just wants to look at the converted value (not copy or move it) : 

• Requestor looks at value. value t • 

• Requestor calls s«lection.Free[@value]; 

• If value.ops is nil or value.ops.f ree is nil: 



• Free calls FreeStd. 

• FreeStd recovers the zone from vaiue.context, does a zone. free 
[©value, value], and replaces value.ops with (free: NopFree, copy Move: nil]. 



• If val ue.ops.f ree is not nil: 



• Free calls vaiue.ops.free [@vaiue] (that is, the manager's ValueFreeProc). 

• The manager's ValueFreeProc recovers the zone from vaiue.context (possibly a 
Held ia a record pointed to by vaiue.context) and releases any resources that 
were allocated in the ConvertProc. This includes not only the obvious freeing of 
storage from the zone (zone.FREE [@vaiue.vaiue] and/or Seiection.FreeContext 
[©value, zone]), but also, for example, closing or deleting any files that were 
created. 



• END 



• If the requestor wants to move or copy the selection: 

• Requestor calls S«l«ction.Move, s«iection.Copy, or Seiection.CopylViove, perhaps 
passing in data: long pointer , which points to a destination for the move/copy. 
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• If value. ops is nil or value. ops. copyMove is nil, CopyMove raises Error 
[Invali'dOperation]. Otherwise, CopyMove calls value.ops.copyMove [@value, 
{copy, move}, data] (that is, the manager's ValueCopyMoveProc). 

• The manager's ValueCopyMoveProc recovers the zone from value. context, gets 
the destination of the move/copy from data (if appropriate), does the move or copy, 
calls s«i«ction.FreeContext [©value, zone] if necessary, does a zone. free 
[@oldValue. value] if necessary. Note: This is freeing the original value. value, not 
the copied one! Now the manager can either leave value.ops.free as is, or replace 
value.ops.free with s«i«ction.FreeStd (if the newly copied value was allocated from 
zone and zone is in value.context), or replace value.ops.free with s«iection.N6pFree 
(if there is nothing left to free). 

• CopyMove replaces value.ops.copyMove with nil to prevent another copy or move 
from being done. 

• Requestor may retain the copied value indefinitely and/or call Selection. Free to free 
the copied value after using it (see above). 

• END 

44.3.4 Sample ConvertProc and Requestor 

In this example of a simple selection manager, the selection is represented internally as a 
pair of indices within a single Mesa string. The string is inside a window. The indices 
designate the first character selected and the position beyond the last character selected. It 
isassume that there are several windows of this type, and that each contains a single string, 
within which selections may be made. It is also assumed that the manager's module 
contains a procedure TextForWindow that obtains the string associated with a window, 
and various other obvious utilities and signals. The procedure Select makes a new 
selection. 

A ConvertProc is shown that implements the common targets. Observe the extremely 
heavy use of the defaults for the ops and context fields in the Value records. Since the 
Selection interface detects these defaults and applies the most common interpretations for 
Copy, Move, and Free, both the requestor and the manager are spared much of the coding 
effort. 

- use dynamic storage for data; global variables make savelrestore awkward 
myZone: UNCOUNTED ZONE a... ; 
SelectionOata: type ■ record [ 

w: vvindow.Handle, - window containing this selection 

left, right: cardinal, 

marked : boolean false] ; 

ValueContext: type * record [ « for use in Value.context fields 
zone: uncounted zone, 
w: window.Handie]; 

Select: procedure [w: window.Handie, left, right: cardinal] ■ { 
text: long STRING M TextForWindow(w]; 

IF text ■ NIL OR left > text.length or right not in [left..text.length] then 
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ERROR BogusSelection; 

^ ^ S«lection.Set( 

myZone.NEw(SeiectionOata [w, left, right]], 
ConvertSeiection, ActOnSelection]}; 

ConvertSelection: s«i«ction.ConvertProc ■ { 

<<[data: ManagerOata, target: Target, zone: uncounted zone, info: Conversioninfo] 

RETURNS [value: Value] >> 
OPEN seiectionOata: narrow [data, long pointer to SelectionOata]; 
WITH i:info select from 
query ■ > 

FOR c: CARDINAL IN [O..LEN<3TH[i. query]) DO 
i.query(c]. difficulty 

IF ^i.query[c].enumeration then select i. query [c]. target from 
window, string, length, position ■ > easy, 
integer « > moderate, 
ENDCASE a > impossible 
else -^enumerated" if i. query [c].target ■ string then moderate 
ELSE impossible; 
enoloop; 
convert a > 

SELECT target FROM 

window a > return([ seiectionOata. w,sei«ction.nopFreeVaiueProcs]]; 

length a > RETURN[[zOne.NEW(LONG CARDINAL 4- 

selectionOata.right - selectionOata.left]]]; 
position a > RETURN[[zone.NEw[LONG CARDINAL 4- selectionOata.left]]]; 
string. Integer a > 

IF selectionOata.right - selectionOata.left > s«iection.maxString Length then 
RETURN[Selection.null Value] 

ELSE { 

bik: Environinent.Block a [LOOPHOLE[@TextForWindow[rec.w].text], 

selectionOata.left, selectionOata.right]; 
r: xstring.ReaderBody «-xstrmg.FromBlock(blk]; 
IF target a integer then { 
bad: boolean 4^ false; 
num: long integer; 
num «-xstring.StringToNumber[@r 

! xstriiig.lnvalidNumber, xstring. Overflow a > 
Chad 4- true; continue}]; 
returnOf bad then Seiection.nui lvalue else 
[zone.NEw[LONG integer 4- num]]]}; 
— target = string 
return[[ 

value: zone.NEw[xstring.ReaderBody 4- r], 
ops: @stringOps, 

context: zone.NEw[ValueContext 4- [zone, seiectionOata.w]] ]]}; 

ENDCASE ; 

enumeration a > if target a string then { 

bIk: Environment.Biock <- [LOOPHOLE[@TextForWindow[selectionOata.w].text], 

selectionOata.left, trash]; 
WHILE biock.startlndex < selectionOata.right oo 
block.stoplndexPlusOne 4- 
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MiN(biock.startindex * Seiection.maxStringLength, selectionOata.rightl; 
IF i.proc([ 

value: zone.NEw(xstring.ReaderSody 4-xstring.FromBiock[blk]], 
ops: ©stringOps, 

context: zone.NEwfVaiueContext [zone, selectionData.w]] ] 

].St0p THEN exit; 

block.startlndex biock.stoplndexPlusOne; 

ENOLOOP}; 

endcase; 
RETURN(seiMtion.nui t Vai ue] }; 

stringOps: s«iection.VaiueProcs [FreeString, CopyString]; 

FreeString: Sei«ction.ValueFreeProc~ fv: VafueHandle] ■ { 
context: long pointer to ValueContext ■ v.context; 
context.zone.FREE[@v.value]; - free the ReaderBody, but not the text bytes 
s«iection.FreeContext( v, context.zone]}; 

CopyString: selection. ValueCopyMoveProc « { 

< <[v: ValueHandle, op: CopyOrMove, data: long pointer] > > 
context: long pointer to ValueContext ■ v.context; 

old: xstring.Reader a v. value; 

IF op ■ move THEN ERROR s«i«ctjon.Error[lnvalidOperation]; 
v.value 4-xstring.CopyReader[old, context.zone]; 
context.zone.FREE[@oidl; 
Seiection.FreeContextf v, context.zone]; 
v.ops.free>-NiL}; 

ActOnSelection: Seiection.ActOnProc « { 

< <[data: ManagerData, action: Action] returns [cleared: boolean false] > > 
OPEN selectionOata: narrow [data, long pointer to SelectionOata]; 

SELEa action from 

mark, unmark « > if selectionOata.marked # (action « mark) then 

InvertHighlightinglrec]; 
save, restore ■ > null; - no special action need be talcen 
delete ■ > null; - deletion is not allowed via this Interface 
clearifHastnsert « > null; - assume that this tool never has the Insertion point 
clear ■ > {myZone.FREE(@data]; cleared 4- true}; 
endcase}; 

Here are three sample requestors that might invoke the above manager code. The first 
requestor wishes to interpret the selection, if possible, as a string of digits and obtain the 
corresponding integer value. The second wishes to open a file whose name is the current 
selection. (Assume the existence of an NSFile routine that deals with XString-format file 
names.) The third wishes to copy the current selection to a Stream unless the selection 
comprises more than 10000 characters. Since copying an NSFIIe to an arbitrary Stream is 
awkward at best, it does not use Convert[file], but rather attempts to get the selection as 
one or more strings to send to the Stream. 

- Example 1: obtain selection as an integer and do something with it 
num: long integer; 
ok: boolean; 

[ok, num] 4h> selection. ConvertNumber[integer] ; 
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IF ok THEN { 

< < do whatever it was we wanted to do with nam >>} 
else{ 

< < report error, or ignore it> >}; 

- Example 2: use current selection as name of file to open 
v: s«tection.Vaiue 4-s«i«ction.Convert(string]; 

file: NSFii«.Handie ^NSFito.nullHandle; 

- if v.value is nil it means there's no selection, or it can't 6e converted to a string, 

- or the string would be so long it's not a reasonable name anyway 

IF V.vaiue # NIL THEN { 

file «-NSFii«.OpenByName[v. value ! NSFii«.Error ■ > continue]; 
S«iection.Free(@ v] }; 

- Example 3: copy selection to a Stream (handle is in sH) unless length > 10000 
bytes: long cardinal; ok: boolean; 

v: s«i«ction.Vaiue; 

[ok, bytes] Seiection.ConvertNumberflength] ; 
IF bk and bytes < » 10000 then { 

V *- s«i«ction.Convert(strtng]; 

IF v.vaiue # NIL THEN PutReader[v, sH] 

ELSE Q ^ s«i«ction.Enumerate[PutReader, string, sH]}; 

PutReader: s«i«ction.EnumerationProc » { 

< < [element: Value, data: RequestorOata] returns [stop: boolean false] >> 
sH: str«ani.Handle ■ data; 
sHJ*utBlock(xstring.Block[element.value].block 

! stream.TimeOut, Volume.) nsufficientSpace » > {stop 4- true; continue}]; 
Sei«ction.Free[@element]}; 

44.3.5 Sample Use of Enumeration 

In this example of the use of the enumeration facility, the user has asked to COPY or move 
the selection to the desktop. The desktop does not particularly care what the selection is; it 
simply requires that it be rendered as one or more files. If the operation is a MOVE, it is 
better not to do it as a copy-then-delete; instead, obtain the existing files and relocate them. 

op: s«i«ction.CopyOrMove — setting is determined by the TIP table interpretor 
IF s«i«ctjon.Enumerate(CopyMoveFileToOesktop, file, @op].aborted then { - error-' }; 



CopyMoveFileToOesktop: Sei«ction.EnumerationProc * { 
op: LONG POINTER TO Seiection.CopyOrMove ■ data; 

file: LONG POINTER TO NSFiie. Reference element. value; - this is readonly until Copied or 
Moved 

S«i«€tion.CopyMove(@eiement, op f » handleForOesktop 
! s«i«ction.Error a > select code from 

~ owner will not let us have it for some reason 
invalidOperation. operationFailed « > {stop <- true: continue}; 

ENOCASE ■ > reject]; 

IF stop then {s«iection.Free{@element]; return}; 
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file 4- element. value; - the value was probabiy changed by Copyl Move 

~ file is now a Reference to a file that is of no interest to the selection manager 

< < create any associated structures necessary for keeping tracJt of the icon > > 

< < might also need to set position attributes, etc.; it would be more efficient 
to set the attributes as part of the Copy or Move, but this would probably 
require an awkward structuring ofCopyMove's data parameter > > 

s«iMtiofi.Free[@element]; - free the storage associated with the Reference 

}; 

Here are two cases where the above code might be invoked. First, assume the selection Is a 
set of documents in an open folder. The folder's conversion proc calls 
CopyMoveFileToOesictop once for each document, with element being the 
NSFti«.References for the already existing files. The ops.copyMove provided by the folder 
implementation either does an NSFile.Copy or an NSFito.Move to transfer the file to the 
desktop directory, and updates element.value if necessary to refer to the new file. If the 
operation is a move, copyMove also reflects the deletion in the folder's window. It might 
also update the selection data if, for instance, the selection is represented internally as a 
range of positional indices within the directory. 

If the selection is a set of printers in the Stair directory icon, no files exist for them until 
they are copied to the desktop. For each printer, the conversion procedure creates a file 
from scratch and passes it to CopyMoveFtieToOesktop. This time, however, ops.copyMove 
calls NSFiLE.Move regardless of the operation requested, since it is not actually possible to 
remove objects from the Star directory. (Alternatively, it could call NSFile.Move to do a copy 
and raise Error[invalidOperation] if asked to do a move.) Meanwhile, the ops.free 
originally included with each element is Selection. NopFree; if the user chooses not to do 
anything with the printer, the Star directory enumeration code simply changes the 
attributes of the file to refer to the next printer in the enumeration and uses the same file 
again. Thus ops.copyMove must also set a flag indicating that a new dummy file must be 
created if there are any more elements in the enumeration. 

The important thing to note is that, in the first example, doing a copy involved creating a 
new file, whereas in the second example it didn't. (Instead, it needed to ensure that the file 
not be re-used when the enumeration continued.) There was no way for the requestor to 
decide whether the object needed to be copied. The decision was left up to the selection 
manager by means of the ops procedure. 



44-30 



Viewpoint Programmer's Manual 



44 



44.4 Index of Interface Items 

Letters in parentheses indicate a description for a 
requestor (R) or a manager (M). 



Item Page 

Action: type 19 

ActOn: procedure 21 

ActOnProc: type 1 5, 1 9 

Can YouCon vert: procedure 10 

CanYouConvertX: procedure 10 

Clear: procedure 21 

ClearOnMatch: procedure 21 

Conversionlnfo: type 14, 15, 16 

Convert: procedure 6 

ConvertX: procedure 6 

ConvertNumber: procedure 9 

ConvertProc: type 14 

Copy: procedure 13 
Copy Move: ValueCopyMoveProc 13 

CopyOrMove: type 1 3(R), 1 8(M) 

Difficulty: type 10 

Discard: procedure 20 

Encapsulate: procedure 20 

^ J encapsulate: Action 20 

Enumerate: procedure 1 1 

EnumerateX: procedure 11 

EnumerationProc: TYPE 12 

Error: error 22 

ErrorCode: type 22 

filewithFeedback: Target 7 

Free: procedure 9 

FreeContext: procedure 19 

FreeStd: ValueFreeProc 17 

HowHard: procedure 10 

HowHardX: procedure 10 

ManagerOata: type 14 

Match: procedure 21 

maxStringLength: cardinal 12(R), 16(M) 

Move: procedure 13 

Nopfree: ValueFreeProc 17 
nopFree Va I ueProcs : 

LONG POINTER TO Val ueProcs 1 8 

nuilVaiue: Value 6 

Query: PROCEDURE 11 

QueryX: PROCEDURE 11 

Query Element: type 1 1 (R), 1 5(M) 

Reconversion: signal 12 

li^ip/ ReconvertDuringEnumerate: 

PROCEDURE 12 



T^Aim 




ReauestorData: type 




Restore* procedure 


20 




50 


Saved: type 


20 


Set: PROCEDURE 


14 


Target: type 


7 


UniqueAction: procedure 


21 


UniqueTarget: procedure 


21 


Value: type 


6(R),15(M)16(M) 


ValueCopyMoveProc: type 


13(R),18(M) 


ValueFreeProc: type 


17 


ValueHandie: type 


9(R).16(M) 


VaiueProcs: type 


1 
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45.1 Overview 

The SimpieTextOisplay interface provides facilities for displaying, measuring, and 
resolving strings of Xerox Character Code Standard text. SimpieTextOisplay deals with 
text in a single font— normally the standard system font— and does not support boldface, 
italic, sub- and superscript, and other text properties. SimpleTextDisplay does not 
implement editable or selectable text, but it provides the building blocks that can be used 
to implement such things. (See SimpleTextEdit.) 

Most clients will be interested mainly in the procedure Stringlnto Window, which simply 
displays one or more lines of text at a given location in a window. 

More sophisticated clients may want to use StringlntoBuffer, which formats text into a 
special bitmap buffer rather than painting it into a window; MeasureString, which 
determines how wide a string would appear if painted into a window without actually 
painting it; or FillResolveBuffer, which computes the position of each character of an 
already displayed line of text. 

All width values taken or returned by SimpleTextDisplay procedures are in terms of screen 
pixels (bits). 

45.2 Interface Items 

45.2.1 Simplest Way to Display Text 

StringintoWlndow: procedure [ 
string: xstring.Reader, 
window: window.Handle, 
place: window.Place, 
lineWidth: cardinal 4-cardinal.last, 
maxNumberOfLines: cardinal 4-1, 

lineToLineDeltaY: cardinal ^0, « default: systemFontHeight 

wordBreak: boolean*- true, 

flags: BitBit.BitBitFlags Display. paintFiags] 

returns [lines, lastLineWidth: cardinal]; 
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Displays string in window, starting at place, place refers to the upper- left corner of the 
first character. Each line is no more than lineWldth pixels wide, and there will be no more 
than maxNumberOfLines lines. If wordBreak is true, Stringlnto Window tries to break 
lines between, rather than within, words. The flags determine what BitBIt function is used 
to place the new bits in the window; the default is to OR them into the window's existing 
bitmap. When a new line is started, its y-position is lineToLineOeltaY below the y-position 
of the previous line; if lineToLineOeitaY is defaulted to 0, each line is systemFontHeight 
pixels below the previous one. lines is the number of lines that were actually painted. 
lastLineWidth is the width of the last line displayed. If the string ends with a carriage 
return and maxNumberOfLines are not exceeded, then lastLineWidth is 0 and lines include 
an empty line following that carriage return. If the string is empty, StringlntoWindow 
returns [lines: 0, lastLineWidth: 0]. 

StringlntoWindow always uses the standard system font, a Flushness of fromFirstChar, 
and a StreakSuccession of fromFirstChar. (See §45.2.4 for an explanation of Flushness and 
StreakSuccession. ) 

systemFontHeight: readonly cardinal; 

systemFontHeight is the height (in pixels) of the system font. 

If systemFontHeight changes due to a runtime addition to the system font, the event 
NewSystemFontHeight will be raised with eventOata a pointer to the systemFontHeight. 

45.2^ StringlntoBuffer 

StringlntoBuffer: procedure [ 
string: xstring.Reader, 
bufferProc: BufferProc, 
lineWidth: cardinal 4-cardinal.Last, 
wordBreak: boolean «- true, 

StreakSuccession: StreakSuccession <- fromFirstChar, 
font: simpieTextFont-MappedFontHandle «-nil] 

returns [lastLineWidth : cardinal, result: Result, rest: xstnng.ReaderBody]; 

Formats string into a bitmap buffer using font and calls bufferProc for each line. (See 
BufferProc below for a description of the parameters passed to bufferProc.) If font is nil, the 
system font is used. StringlntoBuffer stops reading characters in the string and calls 
bufferProc when one of the following events occurs: 

• A character whose TextBIt flags are [stop: true, pad: false] is encountered, such as a 
carriage return. bufferProc is called with a result of stop. The string passed to 
bufferProc ends with the carriage return. 



• The lineWidth (measured in pixels) would be exceeded by formatting the next 
character. bufferProc is called with a result of margin. The string passed to bufferProc 
ends with the last character that did fit (if wordBreak is false) or with the last 
character before the beginning of the word that did not fit (if wordBreak is true). 
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• There are no more characters to be read. bufferProc is called with a result of normal. 
The string passed to bufferProc ends with the last character of the string passed to 
String! ntoBuffer. 

Result: type • {normai, margin, stop}; 

If result m normal, or bufferProc returns continue ■ false, StringI ntoBuffer returns the 
following values: result « the result last passed to bufferProc, rest « a substring 
containing characters not yet processed (resloffset will be the string.limit last passed to 
bufferProc), lastLineWidth ■ the dims.w last passed to bufferProc. 

If result is not normal, and bufferProc returns continue « true, StringlntoBuffer continues 
processing the remainder of string and calls bufferProc again. 

If string is empty, StringlntoBuffer returns [width: 0, result: normal, rest: 
xstring.nuliReaderBody] and does not call bufferProc at all. 

BufferProc: type » procedure [ 
result: Result, 
string: xstring.Reader. 
address: Environment-BltAddress, 
dims: window.Oims. 
bitsPerLlne: cardinal] 
RETURNS [continue: boolean]; 

A BufferProc is called once on each line of text processed by StringlntoBuffer. The 
procedure should return true if it wants StringlntoBuffer to process the remaining text 
(and to call the BufferProc again). The parameters should be interpreted as follows: 

result explains why StringlntoBuffer decided to end the current line of text: 

stop if the line ends with a carriage return character. 

normal if there are no more characters to be processed after this line. In this case, 
StringlntoBuffer ignores the continue boolean that the BufferProc 
returns. 

margin if the line was broken to avoid exceeding the line Width passed to 
StringlntoBuffer. 

string is a substring of the string passed to StringlntoBuffer, which contains exactly those 
characters on this line. If the line ends with a carriage return, the carriage return is the 
last character in string. 

address is the address of the bitmap buffer into which the current line's characters have 
been formatted. 

dims is the dimensions of the formatted part of the bitmap buffer, dims.h is always equal to 
the height of font passed to StringlntoBuffer (or to systemFontHeight if font was nil). 
dims.w is always < = the lineWidth passed to StringlntoBuffer. 

bitsPerLine is the number of bits per bitmap line in the buffer (that is, how many bits to 
add to address to reach the beginning of the next bitmap line). It is always a multiple of 16. 
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Fine point: If the string passed to StringintoBuff er ends in a carriage return, and the BufferProc returns TRUE, the 
BufferProc is called one last time with an empty string (offset and limit both equal to the passed string.limit), an 
empty bitmap (dims. w » 0), and result » normal. 



45.2.3 Measure and Resolve 



GetCharWidth: procedure [char: xchar.Character, 
font: simpi«T«xtFont.MappedFontHandie 4- nil] 
RETURNS [width: cardinal]; 

Returns the width of the specified character in the specified font. If font is nil, the 
system font is used. 

MeasureString: procedure [ 
string: xstnng. Reader, 
iineWidth: cardinal 4-caroinal.last, 
wordBreaic boolean «~ true, 

strealcSuccession: StreakSuccession ^-fromFirstChar, 

font: simpieTextFont-MappedFontHandle 4-nil1 

RETURNS [width: CARDINAL, result: Result, rest: xstring.ReaderBody]; 



MeasureString determines the number of horizontal pixels that displaying string in the 
specified font would take up. If font is nil, the system font is used. If wordBreak is true and 
the string will not fit into IineWidth pixels, MeasureString attempts to end the line 
between words, result is one of the following: ^^^^ 

stop If a carriage return character is encountered in the string before iineWidth 
pixels have been measured. In this case, width is the pixel width of those 
characters up to and including the carriage return, and rest begins with the first 
character following the carriage return. 

margin If the string will not fit within IineWidth horizontal pixels. In this case, width is 
the pixel width of those characters that do fit (possibly backed up to the end of 
the last word that entirely fits on the line, if wordBreak is true), and rest begins 
with the first character that does not fit. 

normal If the string contains no carriage returns and fits entirely within IineWidth 
horizontal pixels. In this case, rest is empty. 

If string is empty, MeasureString returns [width: 0, result: normal, rest: 
xstring.nul I ReaderBody] . 



FillResoiveBuffer: procedure [ 
string: xstring. Reader, 
IineWidth: cardinal ^cardinallast, 
wordBreak: boolean true, 

streakSuccession: StreakSuccession 4-fromFirstChar, 

resolve: ResovleBuffer, 

font: simpieTextFont.MappedFontHandle 4-nil] 

RETURNS [width: cardinal, result: Result, rest: xstring.ReaderBody]; 

FillResoiveBuffer measures the x-offset of the left edge of each character of string relative 
to the left edge of the leftmost character and stores the measurements in the resolve array. 
The measurements are in units of pixels. The offset of the leftmost character is zero. There 
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is one element in the resolve array for each of the bytes (not characters) of string. The 
measurement stored for each byte of string is the measure for the character that the byte is 
a part of. The measure stored for character set shift codes is that of the next actual 
character in the string. (For the meaning of the return values, see the description of 
MeasureString.) 

The resolve buffer must be string.limit-string.offset ♦ 1 words long to avoid smashing 
memory. 

If string.conte)ct.suffixSize • 1 and the string contains no character set shifts (377Bs) (that 
is,if there is one byte per character), then: 

resoive(0] is assigned x-o£fset of the character string.bytes[string.offset], 
resolve(1] is assigned the xrofTset of the character string.bytesCstring.offset -i* 1], 
••••» 

resolve(string. limit-string. off set-1] is assigned the x-offset of the character 
string.bytes(string.llmit-1]. 

If the string does contain 377Bs, then any character set shift bytes ([377B, chset] or [377B, 
377B, 0]) are assigned the same resolve value as the following character code byte. 

In any part of the string that is in Stringletl6 format (2 bytes per character), both bytes of 
each character are assigned the same resolve value. 

If a sequence of characters would be displayed as a ligature— a single graphic representing 
several adjacent characters—then all of those characters are assigned the same resolve 
value. 

In all cases, resolveCstring.limit-string.off set] is assigned the pixel width of the string— the 
same value that is given to the returned value width. 

If string is empty, FIIIResolveBuffer returns [width: 0, result: normal, rest: 
xstring.nullReaderBody] and does not write into the resolve buffer at all. 

ResolveBuffer: type a long descriptor for array [0..0) of cardinal; 

NewResolveBuffer: procedure [words: cardinal] returns [ResolveBuffer]; 

Allocates a resolve buffer of the specified length for later use by FIIIResolveBuffer. Non- 
Si mpielextOispiay clients of TextBIt are also encouraged to obtain their resolve buffers by 
calling this procedure, because SimpleTextOisplay caches resolve buffers for efficiency. 

FreeResolveBuffer: procedure [ResolveBuffer]; 

Frees a resolve buffer allocated by NewResolveBuffer. 

43.2.4 Multinationalltems 

Ftushness: type ■ {flushLeft,fiushRight,fromFlrstChar}; 

A Flushness determines where to display a line of text that does not fill the entire bitmap 
width allotted to it. flushLeft places the leftmost character at the lefl edge of the bitmap. 
flusHRight places the rightmost character at the right edge of the bitmap. fromFirstChar is 
equivalent to flushLeft if the Hrst character of the text has xchar.JoinOirection « 
nextCharloRlght (for example, Latin and most other alphabets); it is equivalent to 
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fiushRight if the first character of the text has JoinOirection ■ nextCharToLeft (for 
example, Arabic and Hebrew letters). 

PeekForFlushness: procedure [requestedFlushness: Fiushness, string: xstring. Reader] 
RETURNS [Flushness]; 

Returns a real flushness (either flushLeft or fiushRight, not fromFirstChar) appropriate for 
the passed requestedFlushness and string. 

StreaicSuccession: TYPE ■ {leftToRight, rightToLeft, f romFirsKhar}; 

PeelcForStreakSuccession: procedure [ 

requestedStreaicSuccession: StreaicSuccession, string: xstring. Reader] 
returns [StreaicSuccession]; 

Returns a real streak succession (either leftToRight or rightToLeft, not fromFirstChar) 
appropriate for the passed requestedStreakSuccession and string. 

45.3 Usage/Examples 

The only non-Xerox Character Code that is significant to SimpleTextOisplay is Carriage 
Return. No other control, characters are recognized. 

All width values taken or returned by SimpleTextOisplay procedures are In terms of screen 
pixels (bits). If the client passes its own font to SimpleTextOisplay, its mica widths should 
be equal to its pixel widths. Fonts passed to SimpleTextOisplay should have no 
measurements actually in micas. 

45.3.1 Stringlnto Window 

rb: xstring.ReaderBody ^xstring.FromSTRING ["This is an example. '*L]; 
Q 4— SimpieTextDisplay.StringlntoWindOW [ 

string: @rb, 

window: window, 

place: [10,10]]; 

45.3.2 StringlntoBuffer 

This example shows an implementation of Stringlnto Window using StringlntoBuffer. 

MyStringlntoWindow: procedure [ 
string: xstring. Reader, 
window: window.Handle, 
place: window.Place, 
llneWidth: cardinal 4-cardinal.last, 
maxNumberOf Lines: cardinal <- 1 , 
lineToLineOeitaY: CARDINAL 4-0, 
wordBreak: BOOLEAN 4- TRUE, 
flags: 8itBit.BitBltFtags 4-Oispiay.paintFlags] 
RETURNS [lines: CARDINAL, iastUneWidth: cardinal] « { 
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MyBufferProc: SimpieTextoispiay.BufferProc ■ { 

oispiay.Bitmap [window, [place, dims], address, bitsPerUne, flags]; 
lines 4- lines + 1; 

place.y 4- piace.y lineToLineOeltaY; 

RETURN [continue: lines < maxNumberOfUnes]; 

}; 

IF lineToLineOeitaY ■ 0 then lineToLineOeltaY ♦-simpieTextoispiay.systemFontHeight; 
lines 4-0; 

[lastLlne Width: lastLineWidth] 4-SimpieTextOispiay.StringlntoBuffer [ 
string: @rb, 

bufferProc: MyBufferProc, 

lineWidth: lineWidth, 
wordBreak: wordBreak]; 

}; 
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45.4 Index of Interface Items 



Item 


Page 


BufferProc: type 


3 


GetCharWidth: procedure 


4 


FiliResolveBuffer: procedure 


4 


Flushness: type 


5 


FreeResoiveBuffer: procedure 


5 


MeasureString: procedure 


4 


NewResolveBuffer: procedure 


5 


NewSystemFontHeight: event 


2 


PeekForFlushness: procedure 


6 


PeekForStreakSuccession: procedure 


6 


Result: type 


3 


ResolveBuffer: type 


5 


StreakSuccession: type 


6 


StringintoBuffer: procedure 


2 


StringlntoWindow: procedure 


1 


systemFontHeight: readonly cardinal 


2 
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46.1 Overview 

The SimpleTextEdit interface provides facilities for presenting short editable pieces of text, 
known as fields, to the user. The user can select, move, copy, delete, and edit the text. Such 
text can contain any sequence of characters supported by the Xerox Character Code 
Standard. 

All the text in a SimpleTextEdit field is displayed in a single font. SimpleTextEdit does not 
provide multiple fonts, boldface, italics, subscript, superscript, paragraph and character 
properties, and other elaborate editor features. 

SimpleTextEdit fields are most appropriate for short pieces of text, preferably less than 30 
lines long. They are not appropriate for editing entire files, for example. 

SimpleTextEdit is primarily intended to support text items in the higher-level 
FormWindow interface but is also provided as a public interface for those clients who may 
need it. Most clients will use FormWindow rather than SimpleTextEdit. FormWindow 
provides support for general forms, including choice, boolean, and command items. 
FormWindow also automatically adjusts the position of other fields when a text field 
becomes taller or shorter. The client of SimpleTextEdit must provide its own procedure for 
this. 

46.1.1 Creating Fields 

Fields are created by calling CreateFieid. Before creating any fields, however, a 
FieldContext must first be created by calling CreateFieidContext. There must be one 
FieldContext for each window that will contain Fields. The FieldContext returned by 
CreateFieidContext should be passed to CreateFieid for each field to be created. When a 
field is created, only the desired window.Oims of the field need to be supplied. 



46.1.2 Displaying a Field 

A field is displayed by calling RepaintField. Before a field can be displayed, it must be given 
a window.Place by calling SetPlace. Failure to call SetPlaca before displaying a field results 
in Error [fteldlsNoPlace]. 
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46.1.3 Notifying a Field 

Notifications are passed to a field by calling TIPResults. SimpleTextEdit attaches neither a 
window dispiayProc nor a tip. Notify Proc to a window. The client provides these procedures 
and then calls RepaintField for display and UPResuits for notifications. If there is more 
than one field in a window or a single field does not occupy an entire window, the client 
must resolve mouse buttons to determine which field should get the notification. 

46.2 Interface Items 



46.2.1 FieldContext 

FieidContext: type ■ long pointer to FieidContextObject; 
FieldCdntextObject: type; 

CreateFieidContext: procedure [z: uncounted zone, window: Window.Handle, 
changeSizeProc: ChangeSizeProc, font: SimpittT«xtFont.i\4appedFontHandle 4-nil] 
returns [fc: FieidContext]; 



A FieidContext holds information that is common to all Fields in a given window. There 
must be exactly one FieidContext associated with any window containing Fields. The 
FieidContext contains such information as the fields' font, the current input focus, the field 
containing the current selection, and so forth. 

CreateFieidContext creates a FieidContext for window, which can be later used to create 
individual Fields (see CreateField). Only one FieidContext should be created for any 
window. All storage associated with the FieidConteict and its Fields is allocated from z. The 
changeSizeProc is called whenever any field's height is changed (see ChangeSizeProc 
below). All text in the FieldContext's fields will be displayed with the supplied font. If font 
is defaulted (the usual case), the standard system font is used. 

DestroyFieidContext: procedure [fc: FieidContext]; 

DestroyFieldContext destroys a FieidContext. If any of fc's fields has the input focus, it 
clears the input focus and turns off the blinking caret. If any of fc's fields contains the 
current selection, it clears and dehighlights the selection. DestroyFieldContext does not 
destroy each field. The client should either call DestroyField on each field before calling 
DestroyFieldContext or else dispose of the associated uncounted zone after calling 
DestroyFieldContext. The client should not call DestroyField after calling 
DestroyFieidContext. 

SetMoveNotifyProc: procedure [fc: FieidContext, proc: Move Notify Proc]; 
MoveNotifyProc: type » procedure [f : Field]; 

A client may set a MoveNotifyProc and it will be called whenever part of the text of field f 
has been moved out of the field. Note that these two items are defined in 
SimpleTextEditExtraS. mesa. 
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46.2.2 Creating Fields 

Field: TYPE > long pointer to FieidObject; 

FieidObject: type; 

CreateField: procedure [ 
dientOata: long pointer, 
context: FieldContext, 
dims: window.Oims, 
initString: xstring.Reader 4-NiL, 
flushness: simpieTextoispiay.Flushness 4-fromFirstChar, 
streakSuccession: simpieTextoispiay.StreakSuccession <-fromFirstChar, 
readonly, password: boolean «- false, 
fixedHeight: boolean false, 
font: simpi«TextFont.MappedFontHandle 4- nil, 
backing Writer: xstring. Writer 4- nil. 
SPEGALKeyboard: Bia€kKeys.Keyboard «-nil] 
returns [f: Field]; 

A Field is an area mthin a window that contains editable text. It is tlie primary object 
manipulated by this interface. 

CreateField creates a field with appropriate attributes. The field uses the window, font, 
zone, and ChangeSizeProc of the passed FieldContext. 

clientOata is a pointer that Is not interpreted but is returned by GetClientOata. Clients 
may use It to associate their own data with each individual field. 

dims are the initial dimensions of the field. As the field's contents change, its height may 
change as well (unless fixedHeight is true). However, the height never becomes smaller 
than dims.h. 

initString is the initial contents of the field, if any. CreateField copies the string; the caller 
continues to own it when CreateField returns. 

flushness controls where to place lines of text that do not fill the entire width of the field. If 
flushness ■ fiushLeft, the leftmost character is next to the field's left edge. If flushness ■ 
flushRight, the rightmost character is next to the field's right edge. If flushness ■ 
fromFirstChar, the field is fiushLeft if its first character has xCharJoinOirection > 
nextCharToRight (for example, Latin and most other alphabets), and flushRight if the first 
character has JoinOirectlon ■ nextCharToLeft (for example, Arabic and Hebrew letters). 

StreakSuccession indicates whether the text of the field flows leftToRight or rightToLeft. 
The default (fromFirstChar) causes the streakSuccession of the field to be determined from 
the first character in the field. Latin and most other alphabets flow leftToRight. Arabic and 
Hebrew flow rightToLeft. 

If readonly is true, the user cannot change the field's contents. SetlnputFocus is a no-op on 
a readonly field, and any call on TIPResults that normally sets the input focus to this field, 
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or change the field's contents does not do so. However, SetVaiue still works on a readOniy imik 
field. 

If password is true, each character of the field is displayed as a *. If a selection is made 
within a password field, and that selection is moved or copied, * characters are moved or 
copied rather than characters from the field's actual backing string. s«i«ction.Convert also 
produces a string of characters. The only way to access a password field's actual content is 
to call GetValue. 

If fixedHeight is true, the Weld's height never changes regardless of the field's content. The 
context's ChangeSizeProc is never called with this field as an argument. 

font allows each field to be a different font. If font is nil, then the system font is used. Note: 
This does not provide for general attributed text in SimpleTextEdit fields. The entire field 
is all the same font. 

If backing Writer is nil (the usual case), SimpleTextEdit allocates the field's backing string 
from the context's zone, expands it as needed, and deallocates it when the field is destroyed. 
If backingWriter is non-NiL, SimpleTextEdit uses it as the backing string and does not 
deallocate it when the field is destroyed. If backingWriter.zone is nil, TIPResults raises 
Error [noRoomIn Writer] whenever it tries to do an operation that would overflow the 
backing string. 

SPEGALKeyboard allows a client-specified interpretation of the central keypad. 
OestroyFieid: procedure [f : Field]; 

Destroys the passed field. If the field has the input focus, it clears the input focus and turns 
off the blinking caret. If the field contains the current selection, it clears and dehighlights 
the selection. OestroyFieid must not be called after the field's context has been destroyed. 

GetValue: procedure [f: Field] returns [xstring.ReaderBody]; 

Returns the field's current contents. The returned string points directly into the field's 
backing storage; it is not copied. 

SetVaiue: procedure [f : Field, string: xstring. Reader, repaint: boolean 4- true]; 

Change the contents of the field. Copies the string, which the caller continues to own after 
SetVaiue returns. Repaints the field unless repaint is false. In that case, the caller should 
call RepaintField before returning to the notifier. If the field has the input focus, it clears 
the input focus and turns off the blinking caret. If the field has the selection, it clears and 
dehighlights the selection. If repaint is true, the field may become taller or shorter, 
triggering a call on the ChangeSizeProc. 

46.2.3 Displaying a Field 

RepaintField: procedure [f: Field]; 

Repaints the field. 
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SetPlace: procedure [f : Field, place: window.P1 ace]; 

Changes the window-relative location of the £leld. This procedure must have been called at 
least once before calling GetBox, RepalntField, or TIPResults; otherwise, calling those 
procedures raises Error [fleidlsNoplace]. Does not repaint the ^eld. SetPlace is intended for 
two primary uses: to set the initial location of a field and to change it from within a 
ChangeSizeProc when another field gets taller or shorter. 

46.2.4 Notifying a Field 

TIPResults: procedure [f : Field, results: TiP.Resuits] 
RETURNS [tookinputFocus, changed: boolean]; 

Passes results to the specified field. The field is changed as appropriate. For example, if 
results contains a PointDown atom, the character closest to the cursor is highlighted. 
Details of the exact processing performed for each possible result are described below. If the 
field's contents are changed while processing the results, changed will be true. If the input 
focus was set to this field, tookinputFocus will be true. Both booleans start out false but 
may become true when strings or atoms are encountered in results. Any TiP.Resuits that 
change the field's contents also cause the field to be repainted; this may cause the field to 
become taller or shorter, triggering a call on its ChangeSizeProc. 

If a string is encountered in results, the string is inserted into the field at the current 
insertion point. This clears the selection if the current insertion point is at either end of the 
selection. The passed field must be the current input focus and not readonly; otherwise, 
the string is ignored. 

The following atoms in results cause actions to be taken. A.n * indicates that the passed 
field must be the current input focus; if not, the atom is ignored. Unless otherwise 
indicated, tookinputFocus and changed remains unaffected after this atom is processed. 

AdjustDown (should be preceded by a coords result): Extends or contracts the current 
selection, depending on coords earlier in results. If there is no current selection, creates 
one extending from the current insertion point to a place determined by coords. This is a 
no-op if the passed field is not the current input focus or selection. 

AdjustMotion (should be preceded by a coords result): Same effect as AdjustDown, 
although a different algorithm is used to determine which endpoint of the selection is being 
moved. 

Backspace*: If the field is not readonly, deletes the character before the insertion point 
and sets changed to true. This clears the selection if the current insertion point is at either 
end of the selection. 

BackWord*: If the field is not readonly, deletes the word before the insertion point and 
sets changed to true. This clears the selection if the current insertion point is at either end 
of the selection. If the field is a password field, acts like a Backspace. 

CopyOown: Calls TiPStar.SetMode [copy]. 

CopyModeDown (should be preceded by a coords result): If the field is not readonly, 
places the caret at an appropriate place in the field, depending upon coords earlier in 
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results, but leaves the selection alone. tooklnputFocus will be true. If the field is readonly, 
this is a no-op and tookl nputFocus is unchanged. 

CopyModeMotion (should be preceded by a coords result): Same effect as 
CopyModeOown. 

CopyModeUp*: If the field is not readonly, inserts the current selection at the current 
insertion point, sets the selection to be the newly inserted text, and calls TiPStar.SetMode 
[normal]. If the selection is not empty, repaints the field and sets changed to true. If the 
field is readonly, this is a no-op and changed remains unaffected. 

OeleteOown: Calls s«i«ction.ActOn [delete], changed becomes true. 

MoveOown: Calls TiPStar.SetMode [move]. 

MoveModeOown (should be preceded by a coords result): Same effect as CopyModeOown. 

MoveModeMotion (should be preceded by a coords result): Same effect as 
CopyModeOown. 

MoveModeUp*: Same effect as CopyModeUp, except that it does a Selection. ActOn [delete] 
on the current selection before setting the selection to be the newly inserted text. Note that 
If the current selection is in a readonly field, no deletion occurs, and it acts exactly like a 
CopyModeUp. 

NewLine*: If the field is not readonly, inserts an Asdi.CR at the current caret position. This 
clears the selection if the current insertion point is at either end of the selection, changed 
will be TRUE. If the field is readonly, is a no-op and changed is unaffected. 

NewParagraph*: Same effect as NewLine. 

PointOown (should be preceded by a coords result and a time result): Sets the current 
selection to be in the passed field. The location of the selection depends upon coords earlier 
in results; the extent (character, word, paragraph) depends on its current extent and time 
earlier in results. tooklnputFocus is true unless the field is readonly. 

PointMotion (should be preceded by a coords result): Moves the current selection within 
the field. If the current selection is not in the field, it sets it there. The location of the 
selection depends upon coords earlier in results. The extent of the selection (character, 
word, paragraph) remains unchanged. tooklnputFocus is true unless the field is readonly. 

PointUp (should be preceded by a time result): Sets the last-click time, which determines 
whether a subsequent PointOown represents a multiple click. 



Stop: Calls TiPStar.SetMode [normal] . 
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46.2.5 Miscellaneous Get and Set Procedures 

GetBox: procedure [f : Field] returns [box: window.Box]; 

Returns the box (dimensions and place) currently occupied by f. box.place is relative to 
the field's window and is always the last value passed to SetPiace. Raises Error 
[fieldlsNopiace] if SetPiace has never been called on this field. 

GetCientData: procedure (f: Field] returns [cilentData: long pointer]; 

Returns the clientOata that was passed to CreateField. 

GetFieldContext: procedure [f : Field] returns [FieldContext]; 

Returns the field context that was passed to CreateField. 

GetFlushness: procedure [f : Field] returns [simpieTextoispiay.Fiushnessl ; 

Returns the current Flushness off. 

GetFont: procedure [f : Field] 

RETURNS [SimpieT«xtFont.MappedFontHandie]; 

GetlnputFocus: procedure [fc: FieldContext] returns [Field]; 

If some field associated with fc has the input focus, it returns that field; otherwise, it 
^ ^.^ ^ returns nil. 

GetCaretPlace: procedure [context: FieldContext] 
RETURNS [place: window.Place]; 

If any field in the FieldContext contains the current type-in point, this procedure returns 
the location of that point. If not, place = [-1,-1]. This is useful for determining that the 
window must be scrolled to make the caret visible to the user. 

GetReadOnly: procedure [f : Field] returns [boolean]; 

Returns the current value of readonly for f. 

GetStreakSuccession: procedure [f: Field] returns [simpieTsxtoispiay.StreakSuccession]; 
Returns the current StreakSuccession off. 

GetWindow: procedure [fc: FieldContext] returns [window: window. Handle]; 
Returns the window that was passed to CreateFieldContext. 
GetZone: procedure [fc: FieldContext] returns [uncounted zone]; 
Returns the uncounted zone that was passed to CreateFieldContext. 
^'Hv^ SetDims: procedure [f : Field, dims: window.Oims]; 
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SetOims sets the dimensions for f . 

SetFixedHeight: procedure [f : simpieTextEdit.Field, 
fixedHeight: boolean]; 

Allows setting the fixed- height attribute for a field. 

SetFlushness: procedure [f: Field, new: simpi«T«xtDispiay.Ftushness] 
RETURNS [oid: Stmpi«T«xtOisplay.FlushneSS]; 

Changes the field's flushness and returns the old flushness. Does not repaint the field. 

SetFont: procedure [f : Field, 

font: simpieTextFont.MappedFontHandle *- nil] ; 

If font ■ NIL, the system font is used. 

SetinputFocus: procedure [f: Field, beforeChar: cardinal «-cardinal.last] ; 

Sets the current input focus to be in this field and places the blinking caret before the 
specified character. If beforeChar is 0, puts the caret before the first character; if it is 
CARDINAL.LAST or Otherwise larger than the length of the backing string, the caret is placed 
after the last character in the field. Does not affect the current selection. 

SetReadOnly: procedure [f : Field, readonly: boolean] returns [oid: boolean]; 

Changes the field's readonly attribute and returns its old value. If this field has the input 
focus and readonly is true, it clears the input focus and turns off the blinking caret. If this 
field has the selection and readonly is false and old is true, it sets the input focus to this 
field and places the caret after the last character in the selection. 

SetSelection: procedure [f: Field, 
firstChar: cardinal 4-0, lastChar: cardinal «-cardinal.last]; 

Sets the current selection to be in this field, covering the specified range of characters. If 
firstChar is 0, the selection begins with the first character of the field. If lastChar is 
CARDINALLAST or Otherwise larger than the length of the backing string, the selection 
extends to the end of the string. Highlights the selection if it is not empty. Does not afTect 
the input focus or caret. 

SetStreakSuccession: procedure [f : Field, new: SimpieTextoispiay.StreakSuccession] 
RETURNS [old: Simpi«TextDispiay.StreakSuccession]; 

Changes the field's StreakSuccession and returns the old StreakSuccession. Does not 
repaint the field. 

SetLosingFocusProc: procedure [fc: FieldContext, proc: LosingFocusProc]; 
LosingFocusProc: type ■ procedure [f : Field]; 

SetLosingFocusProc sets the LosingFocusProc for fc. proc is called whenever a field in fc 
loses the input focus, f is the field that is losing the input focus. This allows the client to 
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undo things that were done when the input focus was set, such as clear softkeys. These 
items are defined in SimpleTextEditExtra.mesa. 

SetUseFinaiRenderingForms: procedure [fc: FieidContext, 
useFinaiRenderingForms: boolean]; 

GetUseFinalRenderingForms: procedure [fc: FieidContext] 
RETURNS (useFinaiRenderingForms: boolean]; 

useFinaiRenderingForms has meaning for languages in which characters are rendered 
differently at the end of a word than in the middle of a word, such as in Arabic. These items 
are defined in SimpleTextEditExtra2.mesa. 

SetCursorKeys: procedure [field: Field, enable: boolean] returns [oidEnable: boolean]; 

SetCursorKeys is for clients that want to enable or disable cursor movement keys in a field. 
Note this is defined in SimpleTextEdit4.mesa. 

LineFromY: procedure [f: Field, y: integer] 

RETURNS [line: cardinal, lineReaderBody: xstring.ReaderBody]; 

LineFromY will find the line of text which is y pixels down from the top of the field f , and 
will return the line number and the ReaderBody describing the line. lineReaderBody 
points directly into the SimpleTextEdit field's backing string and should therefore NOT be 
freed by the client. Note this is defined in SlmpleTextEditS.mesa. 

AppendReader: procedure [f : Field, string: xstring. Reader, repaint: boolean <- true]; 

AppendReader is used by the client to a append string to the end of the backing store for 
field f . The field does not need to have the input focus, and the selection and the input focus 
remain unchanged. If repaint is false, the affected area will be invalidated but not 
validated. If repaint is true, the display will reflect all the changes after returning from 
AppendReader. Note this is defined in SlmpleTextEditS.mesa. 

46.2.6 ChangeSizeProc 

ChangeSizeProc: type ■ procedure [f : Field, oldHeight, newHeight: integer, 
repaint: boolean]; 

Each FieidContext has a ChangeSizeProc associated with it. This procedure is called 
whenever any of its fields is redisplayed and the number of lines of text being displayed has 
changed. It may be called as a result of calling either RepaintFieid. TIPResuits, or SetValue. 
The client is expected to update any affected data structures (such as the window.Place of 
other fields) and then optionally repaint any part of the window that is invalid. (There are 
two exceptions: the ChangeSizeProc is never called on a field for which CreateFleld was 
called with fixedHeight ■ true, and it is not called if both the old and new number of text 
lines require fewer vertical pixels than the height dims.h that was specified to 
CreateFleld.) 

The oldHeight and newHeight parameters are in vertical pixels. inOisplayProc is true if 
the ChangeSizeProc is being called as a result of calling RepaintFieid with repaint ■ true 
(that is, is being called indirectly by window. Validate). 
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If repaint is true, the ChangeSizeProc should not do a window.Validate, because this would 
cause undesirable recursion. 

46.2.7 Errors 

Error: error [type: ErrorType]; 

ErrorType: type ■ {fieldlsNoplace, noRoomIn Writer, lastCharGTfirstChar}; 

Error [fieldisNopiace] is raised by GetBox, RepaintFiieid, and TIPResults if SetPlace has 
never been called on the passed field. Error [noRoomIn Writer] is raised by CreateFieid, 
SetValue, and TIPResults if a non-NiL backingWriter was passed to CreateField, the 
backingWriter has a nil zone, and the desired operation would overflow the string. 

46.3 Usage/Examples 

46.3.1 Selection Management 

If certain atoms (PointDown, PointMotion, AdjustDown, AdjustMotion, Copy Model! p, 
MoveModeUp) are in the Tip.Resuits passed to TIPResults, SimpleTextEdit may become the 
manager of the current selection. The procedure SetSelection also causes SimpleTextEdit to 
manage the curent selection. 

While SimpleTextEdit is managing the current selection, it supports conversions to the 
following s«iection.Targets: shell, subwindow, length, and string. It also supports 
s«iection.Enumerate with a target of string. 

SimpleTextEdit implements the following Seiection.Actions:mark, unmark, clear, delete, 
ciearif Haslnsert, restore, and save. All other Actions are ignored. 

Selection. ActOn [delete] automatically repaints the field that contained the current 
selection; the field may become taller or shorter, triggering a call on its ChangeSizeProc. 
s«i«€tlon.ActOn [delete] is a no-op if the current selection is in a readonly field. 
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46.4 Index of Interface Items 



Item 


Page 


AppendReader: procedure 


9 


ChangeSizeProc: type 


9 


CreateFieid: procedure 


3 


CreateFieidContext: procedure 


2 


OestroyField: procedure 


4 


OestroyFieldContext: procedure 


2 


Error: error 


9 


ErrorType: type 


9 


Field: type 


3 


FieidContext: type 


2 


FieldContextObject: type 


2 


FieldObject: type 


3 


GetSox: procedure 


6 


GetCaretPlace: procedure 


7 


GetClientOata: procedure 


6 


GetFieidContext: procedure 


6 


GetFlushness: procedure 


7 


GetFont: procedure 


7 


GetlnputFocus: procedure 


7 


GetReadOniy: procedure 


7 


GetStreakSuccession: procedure 


7 


GetUseFi nai Render! ngForms: procedure 


8 


GetVaiue: procedure 


4 


GetWindow: procedure 


7 


GetZone: procedure 


7 


LineFromY: procedure 


9 


LosingFocusProc: type 


8 


MoveNotifyProc: type 


3 


RepaintFieid: procedure 


4 


SetCursorKeys: procedure 


9 


SetDims: procedure 


7 


SetFixedHeight: procedure 


7 


SetFiushness: procedure 


7 


SetFont: procedure 


8 


SetlnputFocus: procedure 


8 


SetLosingFocusProc: procedure 


8 


SetMoveNotifyProc: procedure 


3 


SetPlace: procedure 


4 


SetReadOniy: procedure 


8 


SetSeiection: procedure 


8 


SetStreakSuccession: procedure 


8 


SetUseFi nai Render! ngForms : procedure 


8 


SetValue: procedure 


4 


TIPResuits: procedure 


5 
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47.1 Overview 

The SimpleTextFont interface provides access to the default system font that is used to 
display Viewpoint's text, such as the text in menus, the attention window, window name 
stripes, containers, property sheet text items, and so forth. This interface is a specialization 
of the regular font management subsystem. 

47.2 Interface Items 

47.2.1 System Font 

MappedFontOescriptor: type; 

MappedFontHandle: type » long pointer to MappedFontOescriptor; 

MappedFontOescriptor is an opaque type that contains all of the information about a font. 
(All metrics, including the width of each character, are in screen dots, not micas.) 

MappedOefaultFont: procedure returns [MappedFontHandle]; 

MappedOefauitFont returns the client a handle onto the system default font. May raise 
FontNotFound or Problem[badFont]. The implementation of SimpleTextFont expects that 
the default font is available in the system file catalog, with the name System.NovaFont. 

MappedFont: procedure [name: xstring.Reader4- nil] 
RETURNS [ MappedFontHandle]; 

MappedFont returns a handle onto the named system font. The file must be a child of the 
system file catalog. Supplying nil is the equivalent of calling MappedOefaultFont. May 
raise FontNotFound or Problem[badFont]. 

MappedFontFromReference: procedure [NSFiie. Reference] 
returns [ MappedFontHandle]; 
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MappedFontFromReference returns a handle onto the specified font file. May raise 
Problem(badFontl. This is defined in SimpleTextFontExtra2.niesa. 

UnmapFont: procedure [MappedFontHandle]; 

Unmaps a font that was mapped with MappedFant or MappedFontFromReference. 
UnmapFont is defined in SimpieTextFont£xtra.mesa. 

47.2.2 Client-Defined Characters 

AddCIientOefinedCharacter: procedure [ 
width, height: cardinal, 
bitsPerLine: cardinal, 

bits: LONG POINTER, 

offsetlntoBits: cardinal 4-0 ] 
RETURNS [xstring.Character]; 

AddCIientOefinedCharacter adds the client's bitmap to the system font as a new character 
and returns the 16-bit value of the character position it is assigned, offset! ntoBits is a byte 
offset. The new character's TextBlt flags indicate that it is neither a stop nor a pad 
character. At start-up time, at least 100 slots are available for these new characters. [0,26] 
normally displays as the blob character. May raise Probiem(clientCharacterBitsExhausted] 
or Probiem[ciienKharacterCodesExhausted]. If RESUMEd, the character [0,261 is returned. 

The Xerox Character Code Standard sets aside a block of character codes for user 
definition. (See the Xerox Rendering Code Standard, XSIS 068208, page 6.) In Star, it is 
often useful to include a small picture, for example, a 13x13 icon drawing, within a 
message or other text. 

The AddCIientOefinedCharacter procedure provides a convenient way of presenting such 
small pictures within formatted system text. You create a character for the picture, say in 
initialization code, and then simply use that (16-bit) character within ordinary text 
sequences, such as window titles. 

47.2.3 Signals and Errors 

FontNotFound: signal [name: xstring.Reader]; 
If FontNotFound is resumed, the system font is used. 
Problem: signal [code: ProbiemCode]; 
ProbiemCode: type a 

{badFont, clientCharacterCodesExhausted. ciientCharacterBitsExhausted}; 

47.3 Usage/Examples 

SimpieTextFont is a specialization of the regular font management subsystem. 

The font file format is easily parsed, it can be mappable Into read-only virtual memory for 
use, and it can be extended. A single file defines the bitmaps for the Xerox characters in 
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one font face and one font size, such as Bodoni Italic 10. Fine point: In the case in which several 
different font face/sizes have the same pictures, as can occur with some printwheei fonts, use the same file for more 
than one font/face. This subject is outside the scope of this specialized interface, because we are only dealing with 
one font. 

The font file begins with a header that identifies the font and describes the subsequent 
sections. Each subsequent section then contains TextBlt-style information about one 
character set's characters. Fine point: Descriptions of the font management subsystem and the ViewPoint 
font format are to be found elsewhere. 

47.3.1 Adding a Client-Defined Character 

The following example creates a small (13x13) icon and displays it as part of a string: 
mySits: array [0..13) of word [-some bits-]; 

wb: xstring.WriterBody ^xstring.WriterBodyFromSTRINGl" is an icon."]; 
smallPicture:xstring.Character simpieTextFont.AddCIIentOef inedCharacter [ 

width: 13, 

height: 13, 

bitsPerLine: 16, 

bits: @myBits, 

offsetlntoBits: 0]; 

xstring.AppendChar[to: @wb,c: smallPicture]; 

n ^-SimpieTextOisplay.StringintoWindow [ 
string: xstring.ReaderFromWriter[@wb], 
window: window, 
place: place]; 

47.3.2 Acquiring the System Font 

The following example acquires a handle to the system font: 

systemFont: simpieT«xtFont.MappedFontHandle ■ simpi«TextFont.MappedFont(]; 

47.3.3 New System Font 

If the system font changes during runtime the event NewSystemFont will be raised with 
the eventData simpieT«xtFont.MappedFontHandle. 



47-3 



47 



SimpleTextFont 



47.4 Index of Interface Items 



Item Page 

AddClientOefineciCharacter:pROCEDURE 2 
FontNotFound:siGNAL 2 
MappedDefaultFont:PROCEDURE 
MappedFont:PROCEOURE 
MappedFontOescriptor:TYPE 
MappedFontFromReference'.PROCEDURE 
MappedFontHandle:TYPE 
NewSystemFont: event 
Problem: SIGNAL 2 
ProblemCode.'TYPE . 2 

UnmapFont: procedure 2 



SoftKeys 



48.1 Overview 

The SoftKeys interface provides for client-defined function keys designated to be the 
isolated row of function keys at the top of the physical keyboard. It also provides a SoftKeys 
window whose '*keytops" may be selected with the mouse to simulate pressing the physical 
key on the keyboard. Such a window will be displayed on the user's desktop whenever an 
interpretation other than the default SoftKeys interpretation is in effect. (The default is 
assumed to be the functions inscribed on the physical keys.) 

48.2 Interface Items 

48.2.1 Data Structures for SoftKey Labels 

numberOf Keys: cardinal ■ . . . ; — This number is dependent on t/ie physicai keyboard. 

Represents the number of keys in the soft key row. Important: in SoftKeys. mesa, 
numberOfKeys is defined as a constant 8. This constant should not be used. Use the 
SoftKeys£xtra.mesa numberOfKeys public variable. 

LabelRecord: type a record ( 

unshifted: xstring.ReaderBody 4-xstrmg.nuliReaderBody, 
shifted: xstring.ReaderBody 4-xstring.nullReaderBodyl: 

LabelRecord provides a record of two xstring.ReaderBody arrays so that both the shifted and 
unshifted key meanings may be labeled. It is expected that any individual key will have 
either a single unshifted label centered on the picture of the appropriate keytop, or both 
shifted and unshifted labels painted in two lines on the keytop, or no label at all 
(xstring.nullReaderBody for both shifted and unshifted). 

Labels: type « long descriptor for array of LabelRecord; 

Client-owned array of strings to be used as labels on the SoftKeys virtual keytops. The 
SoftKeys procedures expect an array of up to numberOfKeys LabeiRecord's at a time. 
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Clients should see to it that string deallocation does not occur between calls to create and jflii. 
delete a SoftKeys instance. 

Bitmaps may be specified for individual labels by using 
SiinpleT«xtFont.AddClientOefinedCharacter. The current SimpieTextFont implementation 
has a somewhat limited number of available slots for client-defined keys. (See the 
SimpieTextFont interface for more information.) 

48.2.2 Creating and Deleting SoftKeys 

Push: PROCEDURE [ 

table: TIP. Table 

notifyProc: tip. Notify Proc ♦-nil, 
labels: Labels4-NiL, 
hIghilghtedKey: cardinal 4- null Key, 
outllnedKey: CARDINAL 4- nuilKeyl 
RETURNS(window: window.Handie]; 

Push installs the SoftKeys Interpretation in the following way: (1) If there is a non-NiL 
table, it is installed in the tip watershed (see TIPStar); (2) if there is a non-NiL notifyProc, it 
is attached to NormalK«yboard.TIP. The latter has the effect of passing all productions 
matched in NorniaiK«yboard.TIP to your notifyProc. (See Appendix A for a complete listing of 
NormaiKeyiioard.TIP.) 

A SoftKeys window is displayed by using labels to "inscribe" the keytop pictures with the 
new names of the keys. Both the shifted and unshifted state of a key may be labeled. If only 
the unshifted state is relevant, the shifted state may be defaulted to 
xstring.nullReaderBody. If there are fewer strings than keytops needing them, the 
remaining keys are left blank. Extra strings are ignored. Fine point: Bitmaps may be placed on the 
keytops by using siinpi«r«xtFant.AddCnentO«fin«dCharacter. Storage for the label strings is the 
responsibility of the client. Care should be taken to ensure that this storage is kept intact 
between a Push and a Remove of any given SoftKeys interpretation. 

outllnedKey and highlightedKey appear highlighted and/or outlined .when the window is 
initialized. The default is no outlining or highlighting. Key values assume zero indexing 
[O..SoftKaysExtra.numberOfKeys). ( That is, the key marked Center is key 0, Bold is key 
l,and so forth.) 

Push returns a handle to the client's SoftKeys window. Note: There may be more than one 
SoftKeys window, with each client holding the handle to his own. The last Pushed 
interpretation is the one in effect until it is Removed or superseded by another Push. 

Remove: procedure [window: window.Handie]; 

The Remove procedure removes the SoftKeys interpretation and associated SoftKeys 
window. The client is responsible for removing its SoftKeys interpretation when it 
relinquishes control of the selection/input focus [see Selection interface descriptions of 
ActOn and Clear] or the user's attention (as in the case of the keyboard and font keys). A 
SoftKeys window and its associated SoftKeys interpretation constitute a unique SoftKeys 
instance. Any SoftKeys instance may be removed from the stack of SoftKeys instances in 
an order other than the order pushed. 
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Attempts to Remove without the corresponding valid window handle from a Push result in 
the error invalidHandie. 

Fine point: R«mov«, rather tiian Pop, was cliosen to describe the ftinction opposite Push to clarify that this is not a 
txue stack. While Push, as the name implies, acts on the top of the stack, R«inov« does not. It is possible to Remove 
a SoftK«ys window from other than the top of the stack. 

Swap: PROCEDURE [ 

window: window.Handle, 
table: np.Tabiei-NiL. 
notifyProc: np.NotifyProc «-nil, 
labels: Labeis4-NiL. 
KighlightedKey: cardinal 4- null Key, 
outllnedKey: cardinal 4-nultKey]; 

The Swap procedure is a way to exchange SoftKeys interpretations without changing the 
SoftKeys instance. Current examples of use include the keyboard key implementation 
where pressing the More key brings up another group of SoftKeys choices. It is strongly 
suggested that a client utilizing a More key place it on the first soft key (the key marked 
CENTER on the physical keyboard) for a consistent user interface. 

At the time when no SoftKeys interpretation is desired, a single Remove corresponding to 
the original Push is expected. Any number pf Swaps may occur in between. Attempts to 
Swap without the corresponding valid window handle from a Push result in the error 
InvalidHandie. 

48.2.3 Highlighting and Outlining a SoftKeys Keytop Picture 

HighlightThisKey: procedure [ 
window: window.Handle 
key:CARDiNAL 4>nullKey]; 

OutlineThisKey: procedure [ 
window: window.Handle, . 
key: cardinal 4-nullKey]; 

These procedures are provided for those clients where permanent highlighting and/or 
outlining of certain soft keys is desired. (Do not confuse these procedures with the 
highlighting done when a key is selected with the mouse. That highlighting is done 
without client participation.) The first parameter, window, refers to the client's SoftKeys 
window returned from a Push. The cardinal corresponds to the key (zero indexing) to be 
outlined or highlighted whenever the chosen key changes. A key value of null Key undoes a 
key that is currently highlighted (or outlined). A number other than nuilKey or 
C0..SoftK«ysExtra.numberOf Keys) results in NoOp. 

Attempts to call HighlightThisKey or OutlineThisKey without a valid handle from a Push 
result in the error InvalidHandie. 

nullKey: cardinal « last[cardinal]; 

A default value meaning no key, to be used for outiinedKey and highlightedKey. 
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48^4 Retrieving Information About a SoftKeys Window Instance 

Info: PROCEDURE [ 

window: windo«v.Handie] 

RETURNS [ 

table: np.Table. 
notifyProc: Tip.NotifyProc, 
labels: Labels, 
hjghlightedKey:CARDiNAL, 
outilnedKey:CARDiNAL]; 

The Info procedure returns information relevant to the SoftKeys instance related to 
window. If the window handle is not valid, the error InvalidHandle is returned. 



48^5 Errors 

InvalidHandle: error: 

This error is raised if the SoftKeys window handle passed to Remove, Swap, Info, 
HighlightThisKey, or OutllneThisKey is invalid. 

48.3 Usage/Examples 

48^1 Graphics Example 

"When the selection is such that the graphics code talces control, 
the initial graphics code should put up the graphics soft keys: 
graph icsSoftKeys Window ^Push( 
table: graphicsSoftKeysTlPTable, 
labels: graphicsSoftKeyLabels]; 

—where the core of the graphics np.Table looks something like: 
"left-side values are defined in the LevellVKeyS interface 

SELEa TRIGGER FROM 

CenterOown * > Stretch; 

BoldOown M > Magnify; 

ItalicsOown Grid; 

CaseOown, UnderiineOown » > Line; 

DbkUnderlineOown, SuperscriptOown « > Curve; 

StrikeoutOown, SubscriptOown » > Join; 

SuperSubOown, SmallerOown « > Top; 

endcase; 

—andpart of the graphics tip. NotifyProc resembles the following: 
"leftside values are the atom results from the tip. Table 
atom ■ > SELECT result from 

Stretch « > OoMy Stretch Routined; 

Magnify » > OoMyMagnifyRoutined; 

Grid « > OoMyGridRoutined; 

Line »> OoMyLineRoutinen; 

Curve a> DoMyCurveRoutineQ; 
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Join « > OoMyJoinRoutineU; 
Top a > OoMyTopRoutineQ; 
endcase; 

'•When graphics loses the selection, it must dear away its SoftKeys interpretation. 
Remove(graphicsSoftKeysWindow]: 

A client using More as one of its soft keys handles it in hits s TiP.Tabies and Tip.NotifyProc: 

Tip.Tabie entry: 

Center Down m > More; 

NotifyProc entry: 
More • > Swap( 
window: mySoftKeysWindow, 
table: myNextSoftKeysTIPTabie, 
labels: myNextSoftKeyLabeis, 
highilghtedkey: 1]; 

This entry results in an exchange of the client's last SoftKeys interpretation for the next 
one specified, (namely, the installation of the new TiP.Tabie and new labels on the keytops.) 
The second key (bold on the physical keyboard) is highlighted in the SoftKeys window. 
The outlinedKey parameter has been left blank. This defaults to nullKey, in which case no 
key will be outlined. 

48.3.2 Keyboard Manager Example 

This client's (Keyboard Manager) select arm does the right thing for both the 8010 and 
6085 workstation keyboards. 

atom • > SELECT z.a from 

CenterOown • > IF more then softK«ys.Swap [] ELSElnstallKeyboard [labeil]; 

BoldOown m > installKeyboard (Iabel2]; 

ItaiicsOown « > InstallKeyboard [Iabel3]; 

CaseOown, UnderiineOown • > InstallKeyboard [Iabel4]; 

DbkUnderllneOown, SuperscriptOown ■ > InstallKeyboard [labels]; 

StrikeoutOown, SubscriptDown ■ > InstallKeyboard [Iabel6]; 

SuperSubOown a > InstallKeyboard [label?]; - No label? if the machine is an 

mo. 

ObkSmallerOown •> installKeyboard [labels]; — No labels for 8010 either. 
MarginsOown, SmallerOown ■ > ShowKey board []; 
FontOown, OefaultsOown ■ > SetKeyboard []; 

If the user presses the MarginsDown on a 6085 or the Smaller Down on an 8010, he has 
actually invoked the soft key that is labeled SHOW in the soft keys window visible on the 
screen. 
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48.4 Index of Interface Items 



Item Page 

HighlightThisKey: procedure 3 

Info: PROCEDURE 4 

InvaiidHandle: error 4 

LabeiRecord: type 1 

Labels: type 1 

nuilKey: cardinal 3 

numberOf Keys: cardinal 1 

OutlineThisKey: procedure 3 

Push: procedure 2 

Remove: procedure 2 

Swap: procedure 3 



48-6 



49 



StarDesktop 



49.1 Overview 

The StarOesktop interface provides access to assorted facilities related to the ViewPoint 
desktop. 

49.2 Interface Items 

49.2.1 General 

AddReferenceToOesktop: procedure [ 
reference : NSFii*. Reference, 
place:window.Place <- nextPface]; 

hextPlace: window.Place ■ 

Adds an icon to the desktop. The file (reference) must be a child of the desktop file (see 
GeKurrentOesktopFile below.) If there is already an icon at place, the next available place 
is used. 

GetPlaceFromReference: procedure [ref : NSFii«.Reference] 
RETURNS [Window.Place]; 

This returns the location of an icon on the desktop. It may be used with 
AddReferenceToOesktop to place an icon near another icon by passing the return value 
from GetPlaceFromReference to AddReferenceToOesktop. AddReferenceToOesktop 
places the new icon at the next available spot after the place passed in. 

SelectReference: procedure [reference: NSFUe.Reference] 
RETURNS [ok: boolean]; 

Selects the icon associated with the specified reference. SelectReference returns false if 
selection fails (for example, if the reference is not found on the desktop). Each call to 
SelectReference will add that reference to the selection (like doing an extended selection 
with adjust). To select a single icon, call s«iection.Clear followed by a SelectReference. 
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GetWindow: procedure returns [window: window. Handle]; 

Returns the desktop window (that is, the root window for ViewPoint). 

GetSheii From Reference: procedure [ref : NSFiie.Reference] 
returns (sws: starWindowSh«il.Handie]; 

If an icon has a shell currently opened, GetSheii From Reference returns this shell. 

CreateOesktop: procedure [name: xstring.Reader] 
returns [fh: NSFUe.Handle]; 

Creates a new desktop directory and returns a handle to it. name is typically a fully 
qualified three-part user name. It is used by logon plug-in clients, a friends-level facility 
(as opposed to a public facility). 

GetCurrentDesktopFiie: procedure returns [NSFii«.Reference]; 

Every available desktop is an NSFiie with attribute.isOirectory ■ true. Desktops have 
children that are also NSFiles and show up as icons on the desktop (see the ViewPoint 
Programmer's Guide, chapter 3, for more information). GetCurrentDesktopFiie returns the 
NSFiie.Reference for the desktop NSFiie that is currently installed and displayed to the user. 

GetNextUnobscuredBox: procedure [height: integer] returns [window.Box]; 

GetNextUnobscuredBox returns the next available vertical segment of the desktop 
window of height, height, and width the width of the desktop. This is Intended for such 
things as the Attention window and the typing feedback window for JStar. There is no 
guarantee that the box returned will be visible, i.e., the client must ensure that the 
returned box is within the desktop window. 

MakeBusy: procedure [ref: NSFiie.Reference] 
RETURNS [Busytcon.Busy status] ; 

MakeUnbusy: procedure [ref: NSFiie.Reference] 
RETURNS [Busylcon.BuSyStatUS]; 

IsBusy: procedure [ref: NSFiie.Reference] 
RETURNS [yes: boolean]; 

These procedures support the Busylcon interface by allowing the client to make icons busy 
and unbusy and determine if an icon on the desktop is busy. See the Busylcon chapter for 
details on busy icons. These interfaces are deflned in StarDeslctopExtra. 

SetOisplayBackgroundProc: procedure [procedure [window.Handle] ]; 

SetOispiayBackgroundProc allows a client to change the procedure that displays the 
background for the desktop. 
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49.2.2 Atoms 

Several ATOMs are exported by the StarOesktop: 



attemptingLogoff 
desktopWindowAvaiiabie 

fuilUserName 
newicon 

logoff 
logon 

userPassword 



"AttemptingLogofT: Event just before logoff. Can be 
vetoed. Gives clients a chance to veto logoff. 

"DesktopWindowAvaiiabie": Event notified when the 
desktop virindow has been initialized and inserted into 
the window tree. Cannot be vetoed. 

"FuilUserName": This atom is to be used with 
AtomicProfile. 

"Newicon": Event notified when an icon has been 
added to the desktop, either by user copy/move, or by a 
client call to AddRef erenceToOesktop. 

"Logoff: Event occurs after logoff. Cannot be vetoed. 

"Logon": Event notified after successful ViewPoint 
logon. Cannot be vetoed. EventData is NSFiie.Handle 
for the desktop file. 

"UserPassword": Also to be used with AtomicProfile. 



49.3 Usage/Examples 

49.3.1 Adding a Reference to the Desktop 

BuiidFiie: procedure \'-^rms-'\ ■ { 
reference: NSFiie. Reference 

InitiaiizeFile [parent: starOesktop.GetCurrentOesktopFiie[] ]; - local proc 
place:winciow.Place 4- [...]; 



starO«sktop.AddRef erenceToOesktop [reference, place]; 

}; 



49-3 



49 StarDesktop 



49.4 Index of Interface Items 



Item Page 

AddReferenceToOesktop: procedure 1 

attemptingLogoff : Atom.ATOM 2 

CreateOesktop: procedure 2 

desktopWindowAvailabie: Atom.ATOM 2 

fullUserName: Atonn.ATOM 3 

GetCurrentOesktopFiie: procedure 2 

GetNextUnobscuredBox: procedure 2 

GetPlaceFromReference: procedure 1 

GetSheilFromReference: procedure 2 

GetWindow: procedure 2 

IsBusy: procedure 2 

MakeBusy: procedure 2 

MakeUnbusy: procedure 2 

nextPlace: constant 1 

newicon: Atoin.ATOM 2 

SetOispiayBackgroundProc: procedure 3 

SeiectRef erence: procedure 1 

Logoff: Atom^TOM 3 

Logon: Atom.ATOM 3 

userPassword: Atom. ATOM 3 
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50.1 Overview 

StarWindowSheil allows a client to create a Star-like window. A StarWindowSheil window 
has a header that contains a title, commands, and pop-up menus. It may have both 
horizontal and vertical scrollbcu'S. It has interior window space that may contain anything 
the client desires (see Figure 50.1.) StarWindowSheil also supports the notion of "opening 
within." The client is insulated frbm the Implementation-speciHc details of exactly how 
these features are represented on the display as well as how windows are arranged on the 
screen (for example, whether they overlap). 

50.1.1 Client overview 

A StarWindowSheil is a window (see Window interface) that is a child of the desktop 
window. A StarWindowSheil has an interior window that is a child of the 
StarWindowSheil and is exactly the size of the available window space in the shell (that is, 
the StarWindowSheil minus its borders and header and scrollbars). The interior window 
may have child windows created by the client. These children of the interior window are 
called body windows. The client may create an arbitrary number of body windows and may 
arrange them arbitrarily. Note: Because the body windows are children of the interior 
window, they are clipped by the interior window. A client could, for example, create a body 
window that is very much taller than the interior window and accomplish scrolling simply 
by sliding the body window around Inside the interior window (This is what the default 
StarWindowSheil scrolling does; for more detail, see the section on scrolling). 

The StarWindowSheil interface provides a number of facilities for manipulating 
StarWindowShells and their various parts: creating and destroying a StarWindowSheil; 
using body windows, commands and pop-up menus; client TransitionProcs (called 
whenever a StarWindowShell changes state-is opened or closed, for example); scrolling ; 
AdjustProcs and LimitProcs; and displaying and stacking (that is, open- within) 
StarWindowShells. The most commonly used facilities (creating a StarWindowShell and 
body windows) are described here and in the section on interface items. The less commonly 
used facilities are described in each subsection of the interface items. 
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StarWindowSheil 




Interior 




50.1.2 Creating a StarWindowSheil, Handles, etc. 

A StarWindowSheil is created by calling starWindowSheil.Create. There are no required 
parameters, but it is quite common to provide a name and a transitionProc. The name is 
displayed as the title in the StarWindowSheil header. The transitionProc is called 
whenever the StarWindowSheil is opened, destroyed, or "put to sleep," giving the client an 
opportunity to allocate and deallocate storage, open and close files, and so forth. 

StarWindowSheil.Create returns a StarWindowSheil.Handie. A StarWlndowSheil.Handle is a RECORD 
[window. Handle]. Thus any procedure that takes a window. Handle also takes a 
StarWindowSheil.Handie, but not the other way around. (The Mesa compiler automatically 
, strips off the brackets and passes the window.Handle if a StarWindowSheil.Handie is passed). 
In particular, a context may be hung directly off a StarWindowSheil (see the Context 
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interface). The Handle returned by Create is then used as the first parameter to most other 
calls to StarWindowShell. 

The StarWindowShell returned by Create is not displayed on the screen (that is, it. is not 
inserted into the visible window tree). A StarWindowShell may be inserted into the 
window tree by calling StarWindowSh«il.Push. This is usually not done by the client but 
rather by some other part of ViewPoint, such as the desktop implementation. For example, 
when the user selects an icon and presses OPEN or PROPS, the application (actually the 
application's ContainM.GenericProc) creates a StarWindowShell and returns it. The desktop 
implementation then displays the StarWindowShell by doing a starWindowSheiLPush. 

30.1.3 Body Windows 

Body windows are created by calling starWindowSh«li.CreateBody. This returns a 
window.Handle. The client can create an arbitrary number of body windows. Each body 
window is a child of the StarWindowShell's interior window. The body windows may 
overlap or not. They can actually be in any arrangement the client finds useful. Some 
common arrangements of body windows .are as follows: 

• One very long body window. 

This is easy to scroll by simply sliding the body window, which is what the 
StarWindowShell default scolling does. 

• One body window with Body WindowJustFits * true. 

This is one way to display an infinite amount of data, such as a Tajo-like editor. The 
client must keep track of what is currently in the window, use adjust procedures, do 
scrolling, and so forth. This is difficult to implement. 

• Several body windows about the size of the interior, adjacent, non-overlapping. 

This is another way to display an infinite amount of data. The client lets 
StarWindowShell do default scrolling, which slides the body windows up or down and 
then calls the client to supply more body windows when it runs out. The client might 
put one page of text into each body window, supplying pages to StarWindowShell 
scrolling as needed. 

• Several body windows smaller than the interior, adjacent, non-overlapping. 
This can be used to simulate subvdndows. 

Note: Body windows can themselves have child windows, and so on. A client might 
implement frames in a document editor by making each frame a child of a body window. 

The eldest body window may be obtained by calling StarWindowShell. Get Body. All the body 
windows may be enumerated by calling starWindowSheti.EnumerateBodieslnOecreasingY or 
StarWindowSh«il.EnumerateBodieslnlncreasingY. To get the StarWindowShell from any body 
window, use StarWindowShell.ShellFrornChild. Fine point: The client's body windows may not be the only 
child windows of the interior window, and the interior window may not be the only child of the StarWindowShell 
window. Therefore the client should never try to enumerate body windows by calling window.GetChild and 
\window.<3«tSibling starting with the StarWIndowShaif. and the client should never try to get the StarWindowShell 
from a body window by calling vwndow.6«tParant. 

The client may provide a repaintProc and a bodyNotifyProc with each body window. The 
repaintProc is the display procedure that is called by the window implementation 
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whenever part or all of the window needs to be displayed (see window.SetDisplayProc). The 
bodyNotifyProc is a tip. Notify Proc that is attached to the window along with the normal set 
of TIP tables and receives notifications for the window (see TiP.SetNotifyProcAndTable). 
Note: If the client is going to use some ViewPoint interface to turn the body window into a 
particular type of window (such as PormWindow or ContainerWindow), these procedures 
should not be supplied by the client, but rather are supplied by that interface. 

A single body window can be set to fit into the interior window. Any time the 
StarWindowShell's size is changed, the body window's size is changed accordingly. (See 
SetBodyWindowJustFits.) 



50.1.4 Commands and Menus 



Every StarWindowShell can have commands and pop-up menus, as in Figure 50.1. 
Commands are actually individual menu items (M«nuOata.ltemHandle), where the 
MenuOataJtemName appears with a rounded corner box around it. When the user clicks 
over a command, the M«nuOata.MenuProc for that item is called. Commands are specified by 
calling StarWindowSh«H.SetRegularCommands, which takes a ManuOata.MenuHandie. Each 
item in the menu is displayed as a command on the left side of the header. 

A pop-up menu is an entire menu. The menu's title appears with a rounded corner box 
around it on the right side of the shell's header. When the user buttons down over the 
menu's title, a small window appears next to the poimter with one line for each menu item. 
When the user selects one of the items, that item's MenuOata.MenuProc is called. Pop-up 
menus are specified by calling StarWindowSh«ll.AddPopupMenu. 

Facilities are also provided for specifying commands that should appear when a shell has 
other shells opened on top of or within it. (See the section on Push and Pop for a full 
discussion of the "open within" illusion, and the section on commands and menus for a full 
discussion of these extra commands.) 



50.2 Interface Items 

50.2.1 Create a StarWindowShell, etc. 

Create: procedure [ 

transitionProc: TransitionProc 
name:xstrin9.Reader nil, 
namePicture:xstring.Character *~ xchar.null, 
host: Handle nil, 
type: SheilType ^ regular, 
sleeps: boolean false, 
considerShowingCoverSheet: boolean true, 
currentlyShowingCoverSheet: boolean false, 
pushersAreReadonly: boolean false, 
readonly: boolean false, 
scrollOata: ScrollData 4~ vanillaScrollOata, 
garbageCollectBodiesProc: procedure [Handle] nil, 
IsCioseLegaiProc: IsCloseLegalProc 4-NfL, 
bodyGravity: window. Gravity *~ nw. 
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zone: uncounted zone nil] 
RETURNS [Handle]; 

Create makes a StarWindowSheli and returns a Handle to it. The StarWindowSheil 
returned by Create is not displayed on the screen (is not inserted into the window tree). A 
StarWindowSheil may be inserted into the window tree by calling starWindowSheii.Push. 
This is usually not done by the client but rather by some other part of ViewPoint, such as 
the desktop implementation. For example, when the user selects an icon and presses OPEN 
or PROPS, the application (actually the application's Contains. GenericProc) creates a 
StarWindowSheil and returns it. The desktop implementation then displays the 
StarWindowSheil by doing a starWindowSh«ii.Push. 

transitionProc is a procedure that is called whenever the state of the shell is about to 
change. In particular, it is called just before the shell is destroyed. The client uses a 
transitionProc to free any data structures that may have been allocated and associated 
with the shell. TransitionProcs are discussed in later in this chapter. 

name appears as the title in the header of the StarWindowSheil. 

namePicture appears just before the title in the header. This character is usually a small 
icon picture created by SimpieTextFont.AddClientOef inedCharacter. 

host is a StarWindowSheli that this shell is logically attached to. The host shell is not 
destroyed while this shell is open. This is typically used by property sheets to indicate the 
shell that the property sheet is displaying properties of. If host is nil, closing this shell does 
not depend on any other shell. 

type is the type of the shell. Shell placement algorithms may be affected by the type. For 
example, regular shells will not overlap when displayed with Star-style window 
management, while psheet shells may overlap other shells. 

sleeps indicates whether this shell can go into the sleeping starWindowSheil.State. If it is 
FALSE, we assume that the client software does not take advantage of the possibilities of the 
sleeping State (by remembering data from open to open). This argument is used with the 
client's transitionProc, discussed later in this chapter. 

considerShowingCoverSheet and currentlyShowingCoverSheet indicate whether the 
shell should ever possess a cover sheet and, if so, whether the cover sheet should be visible. 
What appears in any cover sheet is governed by a cover sheet implementation. See the 
section on Errors. 

The two readonly arguments define whether this shell is uneditable and whether all shells 
pushed onto this one should be uneditable. readonlyness is really up to client 
interpretation. This information is simply maintained for client convenience. If a shell 
below this one in a push stack has pushersAreReadonly set true, then the implementation 
forces readonly to true. 

scrollData indicates whether vertical or horizontal scrollbars should appear and allows the 
client to supply procedures to be called for various user scrolling actions. (See the section 
on scrolling for full details.) The default will cause vertical scrollbars to appear, but not 
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horizontal. The default scrolling procedures simply slide body windows up or down, left or 
right, as appropriate. 

garbageCoilectBodiesProc is called when a scroll action causes a body window to be placed 
completely outside the shell's interior window. The call thus allows the client an 
opportunity to garbage-collect the body window and associated data structures. (See the 
section on scrolling.) 

isCloseLegaiProc is called when the user attempts to close the StarWindowSheil or when a 
client calls StandardClose, StandardCloseAll, or StandardCloseEverything. This allows the 
client to veto the user's attempt to close the window. If the isCloseLegaiProc returns true, 
the shell is closed; if the isCloseLegaiProc returns false, the shell is not closed. The 
isCloseLegaiProc is also a convenient way for the client to get control when the window is 
being closed. 

bodyGravity argument indicates what value for gravity should be used when the 
implementation adjusts the size of a body window. 

zone defines the storage area from which all the shell data structures are allocated If 

zone* NIL, StarWlndowSheil creates a zone which will be destroyed when the shell is 

destroyed. However, if the client supplies a zone which should be destroyed when the Shell 

is destroyed, then the client should call SetOestroyZoneProc (see below). Fine point: The 

\Mn(iow.Obj«cts themselves are not allocated out of the client's zone. If the client allocates child windows using a 

zone (vMiidow.O«attt or wif«dow.N«w with non-NIL zone), these child windows must be removed from the shell before 

it is destroyed. When the shell's TransitionProc is called with a state of dead, the client should remove those Jtttk, 

windows. 

CreateWithBitmapUnderOption: procedure! 

transitionProc: TransitionProc <- nil, 
• name:xstring.Reader <-NiL, 

na mePi ct u r e : xstring. Cha racter xchar . n u 1 1 , 

host: Handle 4- nil. 

type: SheilType regular, 

sleeps: boolean <- false, 

considerShowingCoverSheet: boolean <-true, 

currently ShowingCoverSheet: boolean false, 

pushersAreReadoniy: boolean false, 

readonly: boolean false, 

scrollData: ScroliOata 4~vaniilaScrollData, 

garbageCoilectBodiesProc: procedure [Handle] 4~ nil, 

isOoseLegalProc: IsCloseKegalProc 4-nil, 

bodyGravity: window.Gravity nw, 

bitmapOption: BitmapUnderOption 4-noBitmapUnder, 

zone: uncounted zone <- nil ] 

returns [Handle]; 

BitmapUnderOption: TYPE a {noBltmapUnder, maybeBitmapUnder, bitmapUnder}; 

CreateWithBitmapUnderOption is identical to Create except for the additional parameter 
bitmapOption. If bitmapOption is noBitmapUnder, no attempt is made to make the shell 
a bitmap-under. If bitmapOption is bitmapUnder, the shell will be a bitmap-under 
window if enough storage space is available. If bitmapOption is maybeBitmapUnder, 



50-6 



Viewpoint Programmer's Manual 



50 



StarWindowShell will use ShellType to decide. Currently only shells of type psheet will be 
bitmap-under windows if bitmapOption is maybeBitmapUnder. Note that 
StarWindowShell will manage the space used for the shell's bitmap- under. Fine Point: 
CreateWithBitmapUnderOption and BitmapUnderOption are currently exported through 
StarWindowSheilExtraS. 

Handle: TYPE ■ record [window.Handle]; 

Create and CreateWithBitmapOption returns a Handle. Any procedure that takes a 
Window.Handle also takes a starWfndowShail.Handle, but not the other way around. (The 
Mesa compiler automatically strips ofT the brackets and passes the window.Handle if a 
StarWindowShell. Handle is passed). In particular, a Context may be hung directly off a 
StarWindowShell (see the Context interface). The Handle returned by Create is then used 
as the first parameter to most other calls to StarWindowShell. 

nullHandle: Handle « [nil]; 

nuilHandle is provided as a convenience. 

ManagerFromShell: procedure [ sws: Handle] 
RETURNS [swmanager: window.Handle]; 

Given a shell (sws) return its swmanager. The swmanager is the descendant window of 
the shell which **just fits" in the shell's interior. It may be used in conjunction with the 
subwindow interfaces to divide the shell into subwindows. See the Subwindow Overview 
Chapter for more information concerning the use of the subwindow package. 

IsCloseLegalProc: type a procedure [sws: Handle, 

ClOSeAil: BOOLEAN 4- false] RETURNS [BOOLEAN]; 

closeAII indicates whether the user selected Close or CloseAll. 
Destroy: procedure [ sws: Handle]; 

Destroys the StarWindowShell and associated data. First, the client's transitionProc is 
called with state = dead. Next, all the shell data is freed. Finally, if the zone was supplied 
by the client then any DestroyZoneProc registered by SetOestroyZoneProc is called. 
Otherwise, theStarWindowShell created zone is destroyed. May raise Error [notASWS]. 

DestroyZoneProc: type » procedure [z: uncounted zone. dientData: long pointer 4-nil1; 

SetOestroyZoneProc: procedure [ 

sws: Handle, proc: DestroyZoneProc 4- OefaultOestroyZoneProc. 

clientOata: long pointers- nil] returns [oldProc: DestroyZoneProc, oldCiientData: 
long pointer]; 

A DestroyZoneProc is called at the end of the process of destroying a shell, allowing the 
client to destroy a zone that was created before the shell was created. That is, if the client 
supplies a zone parameter to Create, then destroying that zone should be done in a 
DestroyZoneProc. SetOestroyZoneProc associates a proc with the sws. oldProc and 
oldClientOata are the previous values or NIL. See Usage/Examples. 
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OefauitOestroyZoneProc: OestroyZoneProc; 

OefauitOestroyZoneProc calls Heap.Oelete, so it may be used by clients that use the Heap 
package for the zone parameter to Create. 

GetOestroyZoneProc: procedure (sws: StarWindowSheil.Handie] 
RETURNS (oidProc: OestroyZoneProc, oldCIIentData: long pointer]; 

GetOestroyZoneProc returns the current settings for OestroyZoneProc and clientData. 
Fine point: OestroyZoneProc, SetOestroyZoneProc, GetOestroyZoneProc and OefauitOestroyZoneProc are 
defined in StarWindowShellExtra5.niesa 

SheliType: type ■ {regular(0),i(eyboard, psheet, attention, static Jast(1 5)}; 

SheilType influences how a shell behaves in several regards, regular shells have a ? 
command, a Close command, and a Close All command if opened on top of another shell. 
With Star-like overall screen management, regular shells do not overlap; they change size 
whenever a window is opened or closed, psheet shells do not have any StarWindowShell- 
supplied commands and freely overlap other shells. The PropertySheet interface uses 
psheet shells to create property sheets, static shells are exempted from any overall screen 
management; for example, a static shell is not shrunk to make room for a regular shell 
when the overall screen management is Star-like. Some clients may find this useful. Most 
clients do not use keyboard, psheet, or attention types. 

StandardClose: procedure [sws: Handle] returns [Handle]; 

StandardCloseAll: procedure [sws: Handle] returns [Handle]; 

StandardOose and StandardCloseAll provide procedural access to the Close and Close All 
commands that are placed in a shell's header automatically by StarWindowShell. These 
procedures call the client's isCloseLegalProc and transitionProc, just as if the user had 
selected the command. If StandardClose or StandardCloseAll is not successful, the return 
parameter is the shell that did not close; otherwise, the return parameter is NIL. May raise 
Error [notASWS]. 

StandardCIoseEverything: procedure returns [notCIosed: Handle]; 

StandardCloseEverything closes all open StarWindowShells. Logoff uses this procedure. 
notCIosed is the first window that could not be closed because its IsCloseLegalProc 
returned false. All windows that can be closed will be. If notCIosed is nil, then all windows 
are closed. 

NewStandardCloseEverything: public procedure 

RETURNS [numberLeftOpen: cardinal <-0, lastNotClosed: Handle <- nullHandle]; 

This procedure is the same as StandardCloseEverything except that it also returns the 
number of shells that vetoed close. NewStandardCloseEverything is defined in 
Star WindowShellExtra. mesa. 

SetPreferredOims: procedure [ sws: Handle, dims: window.Oims ]; 
SetPreferredPlace: procedure [sws: Handle, place: wndow.Place]; 
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SetPreferredDims and SetPreferredPlace provide a suggestion as to the desired size and 
location of the shell. Depending on the overall screen management in effect at the time the 
shell is displayed, these preferred values may be ignored. May raise Error [notASWS]. 

GetPreferredDims: procedure [ sws: Handle] returns [box: window.Oims]; 

GetPreferredPlace: procedure [sws: Handle] returns [box: wndow.Place]; 

GetPreferredDims and GetPreferredPlace return the current preferred dims and place of 
sws. May raise Error [notASWS]. These are defined in StarWindowShellExtra4.mesa. 

SetPreferredlnteriorOims: procedure [sws: Handle, dims: Window.Oims); 

SetPreferredlnteriorOims makes the shell just big enough to fit around dims. This means 
the interior window will be of size dims. SetPreferredlnteriorOims is defined in 
StarWindowShellExtra2.mesa. 

[fine point: there is a Adding procedure used when sizing and placing shells on the desktop pattern that may 
cause the shell to be resized or moved ±2 bits.] 

50.2.1.1 IsCloseLegalProc 

The client may supply an IsCloseLegalProc when a StarWindowShell is created or later by 
calling SetisCloseLegalProc. This client procedure is called when the user attempts to close 
the StarWindowShell or when a client calls StandardCIose, StandardCloseAll, or 
StandardCIoseEverything. This allows the client to veto the user's attempt to close the 
window. If the IsCloseLegalProc returns true, the shell is closed; if the isCloseLegaiProc 
returns false, the shell is hot closed. The IsCloseLegalProc is also a convenient way for the 
client to get control when the window is being closed. 

IsCloseLegal: procedure [ sws: Handle, closeAil: boolean] returns [boolean] ; 

IsCloseLegal calls the client's IsCoseLegalProc and returns the value returned from that 
call. If there is no isCloseLegaiProc, IsCloseLegal returns true. May raise Error [notASWS]. 

IsCloseLegalProcReturnsFalse: IsCloseLegalProc; 

GetlsCioseLegalProc: procedure [sws: Handle] 
RETURNS [ IsCloseLegaiProc ]; 

GetlsCioseLegalProc returns the current IsCloseLegalProc associated with sws. May raise 
Error [notASWS]. 

SetisCloseLegalProc: procedure [ 
sws: Handle, 
proc: IsCloseLegaiProc ]; 

SetisCloseLegalProc sets the IsCloseLegaiProc for sws. May raise Error [notASWS]. 

Note: IsCloseLegaiProc: type « procedure [... should be in this interface and will be added 
in the next release. 
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50.2.1.2 Miscellaneous Get and Set Procedures 

Several procedures that set and return values logically associated with a StarWindowShell 
are provided. 

GetContainee: procedure [sws: Handle] returns [contain««.Oata]; 
GatHost: procedure [sws: Handle] returns [Handle]; 

GetName: procedure [sws: Handle. cailBack: procedure [name: xstrmg.Reader]]: 
GetReadonly: procedure [sws:Handle] returns [boolean] ; 
GetType: procedure [sws:Handle]RETURNS[ShellType]; 

These procedures return the obvious value associated with sws. May raise Error 
[notASWS]. 

GetZone: procedure [sws: Handle] returns [uncounted zone); 

When a StarWindowShell is created the client may specify a zone, or the StarWindowShell 
implementation may create a zone which will contain all shell-related data items. The 
client can use this zone which is returned by GetZone. If the zone was created by the 
StarWindowShell implementation then it will be completely garbage-collected when the 
shell is destroyed. However, if the zone was supplied by the client then the fate of the zone 
is up to the client. See also the Destroy ZoneProc discussion in section 50.2.1. May raise 
Error [notASWS]. 

HaveOisplayedParasite: procedure [sws: Handle] returns [boolean]; 

HaveOisplayedParasite returns true if a shell is displayed that has this shell (sws) as its 
host. (See host under StarWindowSheil.Create.) For example, if a property sheet that was 
created with host = sws is currently displayed, then HaveOisplayedParasite [sws] returns 
TRUE. May raise Error [notASWS]. 

SetContainee: procedure [sws: Handle, file: Contain««.OataHandle]; 

SetHost: procedure [sws. host: Handle] returns [old: Handle]; 

SetName: procedure [sws: Handle, name: xstring.Reader]; 

SetNamePtcture: procedure [sws: Handle, picture: xstrmg.Character]; 

SetReadOnly: procedure [sws: Handle, yes: boolean]; 

SetSleeps: procedure [sws: starWindowSheii.Handle. sleeps: boolean] 
RETURNS [old: boolean]; 

sleeps a TRUE means the shell can be put to sleep. It is the same as the sleeps parameter to 
Create. Fine point: This procedure is currently exported through StarWindowSheilExtra. 

These procedures set the obvious value associated with sws. May raise Error [notASWSl. 
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50.2.2 Body Windows 

A StarWindowSheil is a window (see Window interface) that is a child of the desktop 
window. A StarWindowSheil has an interior window that is a child of the 
StarWindowSheiland is exactly the size of the available window space in the shell (that is, 
the StarWindowSheil minus its borders and header and scrollbars). The interior window 
may have child windows created by the client. These children of the interior window are 
called 6od|y windows. The client may create an arbitrary number of body windows and 
arrange them in an arbitrary fashion. Note: Since the body windows are children of the 
interior window, they are clipped by the interior window. A client could, for example, 
create a body window that is very much taller than the interior window and accomplish 
scrolling by simply sliding the body window around inside the interior window. (This is 
actually what the default StarWindowSheil scrolling does; for more detail, see the section 
on scrolling). 

Body windows are created by calling StarWindowShell.CreateBody. This returns a 
window.Handle. The client ca,n create an arbitrary number of body windows. Each body 
window is a child of the StarWindowSheii's interior window. The body windows may 
overlap or not. They can be in any arrangement the client finds useful. Some common 
arrangements of body windows are as follows: 

•One very long body window. 
This is easy to scroll by simply sliding the body window, which is what the 
StarWindowSheil default scrolling does. 

•One body window with Body WindowJustFits « true. 

This is one way to display an infinite amount of data, such as a Tajo-like editor. The 
client must keep track of what is currently in the window, use adjust procs, do 
scrolling, and so forth. This is difficult to implement. 

•Several body windows about the size of the interior, adjacent, non-overlapping. 
This is another way to display an infinite amount of data. The client lets 
StarWindowSheil do default scrolling, which slides the body windows up or down and 
then calls the client to supply more IxKiy windows when it runs out. The client might 
put one page of text into each body window, supplying pages to StarWindowSheil 
scrolling as needed. 

•Several body windows smaller than the interior, adjacent, non-overlapping. 
This can be used to simulate subwindows. 

Note: Body windows can themselves have child windows, and so on. A client might 
implement frames in a document editor by making each frame a child of a body window. 

CreateBody: procedure [ 
sws: Handle, 

repaintProc: procedure [window.Handle] 4-nil, 
IsodyNotifyProc: tip. Notify Proc nil, 

box: window.Box 4- [[0,OL[0,29999]] ] returns [window.Handle]; 

CreateBody creates a body window that is a child of the interior window of sws. 
repaintProc is the display procedure that is called by the window implementation 
whenever part or all of the body window needs to be displayed (see window.SetOisplayProc). 
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bodyNotifyProc is aTip.NotifyProc that is attached to the window along with the normal set 
of TIP tables and receives notifications for the window (see Tip.SetNotifyProcAndTable and 
TiPStar.NormalTable). Note: If the client is going to use some ViewPoint interface to turn 
the body window into a particular type of window (such as Form Window or 
Container Window), these procedures should not be supplied by the client but are supplied 
by that interface, box indicates the size and location of the body window within the shell's 
interior window. If box.dims.w and/or box.dims.h is zero, the body vdndow takes on the 
dims.w and/or dims.h of the shell's interior window. May raise Error [notASWS]. 

DestroyBody: procedure [body: window.Handiel; 

OestroyBody destroys body and any Context data associated with it. May raise Error 
[notASWS]. 

GetBody: procedure [sws: Handle] returns [window.Handle]; 

GetBody returns the eldest body window of sws. The client's body windows may not be the 
only child windows of the interior window, and the interior window may not be the only 
child of the StarWindowShell window. Therefore the client should never try to enumerate 
body windows by calling window. GetChi Id and window.GetSibling starting with the 
StarWindowShell. The EnumerateBodiesXXX procedures should be used instead. May 
raise Error [notASWS]. 

SheilFromChild: procedure [child: window.Handle] returns [ Handle]; 

ShellFromChiid returns the shell given any body window or any descendant window of the 
shell. The client's body windows may not be the only child windows of the interior window, 
and the interior window may not be the only child of the StarWindowShell window. 
Therefore the client should never try to get the StarWindowShell from a body window by 
calling Window. GetParent. May raise Error [notASWS]. 

EnumerateBodiesinincreasingY: procedure [ 
sws: Handle, proc: BodyEnumProc] returns (window.Handle nil]; 

' EnumerateBodieslnOecreasingY: procedure [ 

sws: Handle, proc: BodyEnumProc] returns [window.Handle <- nil]; 

BodyEnumProc: type ■ procedure [victim: window.Handle] 
returns [stop: boolean *- false]; 

The EnumerateBodiesln... procedures enumerate ail the body windows of sws, calling proc 
for each body window until proc returns stop ■ true. EnumerateBodiesinincreasingY 
enumerates the body windows in increasing order of window.GetBox [body].place.y, and 
EnumerateBodieslnOecreasingY enumerates the body windows in decreasing order of 
Window.GetBox [body].place.y. Each procedure returns the last body window enumerated 
or NIL if all body windows were enumerated. Thiese procedures are especially handy for 
clients that do their own scrolling. To minimize repainting when scrolling a set of body 
windows upward, it is important to move the upper ones first, and vice versa. May raise 
Error [notASWS]. 

GetBodyWindowJustFits: procedure [sws: Handle] returns [ boolean]; 
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SetBodyWindowJustFits: procedure [sws: Handie, yes: boolean]; 

Some clients may wish to have a single body window that is automatically resized by the 
StarWindowShell implementation to just fit within the interior of the shell. Such a body 
window is said to have BodyWindowJustFits = true. If BodyWindowJustFits = false (the 
default for CreateBody), StarWindowShell leaves the body window's dimensions alone, 
even though the body window may stick out or not fill the shell. GetBodyWindowJustFits 
and SetBodyWindowJustFits allow the client to determine and set this just-fits behavior 
for a single body window. Setting just-fits when there is more than one body window yields 
undefined results. May raise Error [notASWS]. 

GetAvaiiableBodyWindowOims: procedure [sws: Handle] 

RETURNS [Window.Oims]; 

GetAvaiiableBodyWindowOims returns the current dimensions of the Interior window of 
sws. May raise Error [notASWS]. 

IsBodyWindowOutOfinterior: procedure [body: window.Handie] 

RETURNS [boolean]; 

IsBodyWindowOutOfinterior returns true if all of body is sticking out of the interior 
window of its shell. i.e. none of body is visible in its parent. May raise Error [notASWS]. 

InstallBody: procedure [sws: Handle, body: window.Handie]; 

InstailBody installs a previously created window into a StarWindowShell, thus making the 
window a body window. Most clients do not need to use this procedure. May raise Error 
[notASWS]. 

DestailBody: procedure [ body: window.Handie]; 

OestaiiBody removes body from its StarWindowShell. Most clients do not need to use this 
procedure. May raise Error [notASWS]. 



50.2.3 Commands and Menus 

Every StarWindowShell can have commands and pop-up menus, as in Figure 50.1. 
Commands are actually individual menu items (iManuOata.ltemHandle), in which the 
M«nuOata.ltemName appears with a rounded comer box around it. When the user clicks 
over a command, the MenuOata.lVlenuProc for that item is called. Commands are specified by 
calling StarWindowShaii.SetReguiarCommands, which takes a ManuOata.MenuHandle. Each 
item in the menu is displayed as a command on the left side of the header. 

A pop-up menu is an entire menu. The menu's title appears with a rounded corner box 
around it on the right side of the shell's header. When the user buttons down over the 
menu's title, a small window appears next to the pointer with one line for each menu item. 
When the user selects one of the items, that item's MenuOata.MenuProc is called. Pop-up 
menus are speciHed by calling starWindowShelLAddPopupMenu. 
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The window.Handle that is passed to the MenuOata.MenuProc for a command or pop-up menu 
item is the window.Handle for the StarWindowShell that the command or pop-up menu is 
currently displayed in, 

StarWindowSheils that are of type regular (see starWindowSheli.SheilType) always have 
system commands leftmost in the header. When a shell is directly on the desktop, the 
system command is Close. When a shell is opened within another, the system commands 
are Close and Close AH . 

Note: Commands may be added to and removed from a StarWindowShell by using 
M«nuOata.Addltem,and so forth. 

The implementation automatically overflows the rightmost commands into an overflow 
pop-up menu when all of them will not fit in the header. If all the pop-up menus will not fit 
in the header, the leftmost items are overflowed into the rightmost pop- up menu. The 
rightmost pop-up menu is always guaranteed to be displayed, because shells are not 
allowed to be so small that no pop- up menu will fit. 

SetReguiarCommands: PROCEDURE [ 

sws: Handle, commands: McnuOata.MenuHandle] ; 

SetReguiarCommands associates commands with sws. May raise Error [notASWSj. 

GetRegularCommands: procedure [sws: Handle] 
RETURNS [MenuOata.MenuHandle]; 

GetRegularCommands returns the regular commands associated with sws. May raise Error 
[notASWS]. 

AddPopupMenu: procedure [ 

sws: Handle, menu: MenuOata.MenuHandle] ; 

AddPopupMenuX: procedure [ 

SWS: StarWindowSh«il.Handle. menu: McnuOata.MenuHandle. repaint: boolean]; 

AddPopupMenu and AddPopupMenuX add menu to the available pop-up menus in sws. 
The title of menu is displayed in the StarWindowShell header with the small pop-up menu 
symbol («) just to the left of it, enclosed in a rounded corner box. Note: Any arbitrary 
symbol (less than the height of the system font) can be part of the title by using 
SimplcTextFont.AddClientOefinedCharacter. AddPopupMenu causes an immediate 
redisplay of the header. AddPopupMenuX only repaints if repaint « true. May raise Error 
[notASWS]. 

SubtractPopupMenu: procedure [ 

sws: Handle, menu: M«nuOata.MenuHandle] ; 

SubtractPopupMenuX: procedure [ 

SWS: starWindowSheiLHandle. menu: MenuData.MenuHandle. repaint: boolean}; 

SubtractPopupMenu and SubtractPopupMenuX remove menu from sws. 
SubtractPopupMenu causes an immediate redisplay of the header. SubtractPopupMenuX 
only repaints if repaint » true. May raise Error [notASWS]. 
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EnumeratePopupMenus: procedure [sws: Handle, proc: MenuEnumProc]; 

Enumerates the pop-up menus associated with the shell. 

EnumerateAllMenus: procedure [sws: Handle, proc: MenuEnumProc]; 

Enumerates every menu associated with the shell. This includes pop-ups, regular 
commands, topPushee commands from the shell underneath, etc. Fine point: This procedure is 
currently exported through StarWindowSh«ilExtra. 

EnumerateDispiayedMenus: procedure [sws: Handle, proc: MenuEnumProc]; 

Enumerates every menu visible in the shell. Tliis includes pop-ups, regular commands, 
topPushee commands from the shell underneath, etc. Fine point: This procedure is currently 
exported through StarWindowSh«iiExtra6. 

MenuEnumProc: type ■ procedure [menu: M«nuOata.MenuHandle] 
returns [stop: boolean <- false]; 

50.2.3.1 Pushee Commands 

Facilities are also provided for specifying commands that should appear when a shell has 
had other shells opened on top of or within it. These facilities are useful only to a client that 
implements some type of open-within capability, such as folders and file drawers. (See the 
section on commands and menus for a full discussion of the "open within" illusion.) These 
extra commands come in three sets: the set that should be displayed when this shell is just 
below the top of the install stack, the set that should be displayed when this shell is 
anywhere in the install stack, and the set that should be displayed if this shell is at the 
bottom of an install stack. These are the so-called TopPushee, MiddlePushee, and 
BottomPushee commands. 

Figure 50.2 depicts how these pushee commands, if supplied, will affect the commands 
visible in a given shell's header. In Figure 50.2, Shell B is Pushed on top of Shell A and 
Shell C is Pushed on top of Shell B. If Shell A is the only shell displayed, Shell A's system 
and regular commands appear in the shell's header. With Shell B Pushed on top of Shell A, 
Shell B's system and regular commands appear as well as Shell A's bottom pushee, middle 
pushee, and top pushee commands. This is because Shell A is on the bottom, in the middle, 
and just below the top of the stack of shells. With Shell C Pushed on top of Shell B, Shell A's 
bottom pushee and middle pushee commands appear, but not Shell A's top pushee 
commands. Shell B's top pushee and middle pushee commands appear, but not its bottom 
pushee commands. 

Caution: The window.Handle passed to the MenuOata.MenuProc for any pushee command is 
the window.Handle of the StarWindowSheil that the command is currently displayed in, not 
the StarWindowSheil that the command was originally associated with. If the client wants 
to be able to recover the StarWindowSheil that the command was originally associated 
with, it may be saved as the MenuOata.ltemOata. 

SetBottomPusheeCommands: procedure [ 

sws: Handle, commands: MenuOata.MenuHandle] ; 
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SetMiddlePusheeCommands: procedure [ 
sws: Handle, commands: MenuOata.MenuHandle] ; 

SetTopPusheeCommands: procedure [ 

sws: Handle, commands: MenuOata.MenuHandle] ; 

GetPusheeCommands: procedure [sws: Handle] 

RETURNS [bottom, middle, top: MenuOata.MenuHandle]; 

May raise Error [notASWS]. 



A's system menu 
A's regular menu 



Shell A 



Desktop 



B's system menu 

B's regular menu 

A's bottom pushee menu 

A's middle pushee menu 

A's top pushee menu 



Shell B 



Cs system menu 

Cs regular menu 

B's middle pushee menu 

B's top pushee menu 

A's bottom pushee menu 

A's middle pushee menu 



Shell C 



Figure 50-2. Install Stack of Window Shells 
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i30.2.4 TransitionProcs 

A StarWindowShell is always in one of three states: awake, sleeping, or dead. The awake 
state indicates that the shell is currently displayed. The sleeping state indicates that the 
shell still exists but is not being displayed and therefore resources associated with the 
display state should be freed. The dead state Indicates the shell is about to be destroyed 
and therefore all resources associated with it should be freed. 

Every StarWindowShell can have a client-supplied TransitlonProc associated with it. This 
TransitlonProc is called whenever the shell's state changes. The client may then do 
whatever is necessary in terms of allocating or freeing resources. 

The client may call starWindowSheil.Create [ ... sleeps: false ... ] to indicate that the 
application does nothing interesting with the sleeping state. This may cause routines that 
would otherwise put the shell in sleeping state (say on a close, where it might be quickly 
reopened) to put it in dead state instead.. 

State: type « (awake(O), sleeping, dead, last(7)}; 

TransitlonProc: type m procedure [sws: Handle, state: State]; 

The TransitlonProc is a client-supplied procedure responsible for allocating or deallocating 
client data structures when sws's state changes, state is the new state of sws. 

When the TransitlonProc is called with state ■ dead, the zone associated with the shell 
must not be destroyed yet. If the zone was supplied by the client and should be destroyed, 
this must be done in a DestroyZoneProc which will be called later during the Destroy 
process. See also the DestroyZoneProc discussion in section 50.2.1 and the GetZone 
discussion in 50.2.1.2. 

GetSleeps: procedure[sws: Handle] returns [boolean]; 

GetSleeps returns the value of the sleeps parameter that was passed to Create when sws 
was created. If true, then the application responsible for this shell can deal with the 
sleeping state. May raise Error [notASWS]. 

GetState: procedure [sws: Handle] returns [ State ] ; 

GetState returns the current state of sws. May raise Error [notASWS]. 

GetTransitionProc: procedure [sws: Handle] returns [TransitlonProc]; 

GetTransitlonProc returns the current TransitlonProc associated with sws. May raise Error 
[notASWS]. 

SetTransitionProc: procedure [sws: Handle, new: TransitlonProc] 
RETURNS [ old: TransitlonProc]; 

SetTransitionProc sets the current TransitlonProc for sws and returns the old one. May 
raise Error [notASWS]. 
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SetState: procedure [sws: Handle, state: State] ; 

SetState sets the state of sws and calls the client's Transit! onProc as appropriate. Most 
clients will not call this procedure. May raise Error [notASWS]. 

SieepOrOestroy: procedure [Handle] RETURNS(Handie]; 

SleepOrOestroy either puts the shell in the sleeping state or destroys the shell, depending 
on the value of the sleeps boolean that was passed to Create when the shell was created. If 
the shell has the ability to sleep (sleep ■ true), then the shell is put into the sleeping state; 
otherwise, the shell is destroyed. The same shell Is returned if the shell was put in the 
sleeping state. This returned Handle should be kept somewhere for later use; otherwise, 
the shell will be lost. A nil handle is returned if the shell was destroyed. This procedure 
might be used by the desktop implementation when a shell is closed. May raise Error 
[notASWS]. 



50.2.3 Scrolling 

Only part of an object is usually visible to the user at any one moment in the interior of a 
StarWindowShell. The user can request to see more of the object by scrolling the contents 
up or down inside the shell. The user can perform three kinds of scrolling by using the 
scrollbars pictured in Figure 50.1. (1) He can move the contents a little at a time by 
pointing at the arrows (up, down, left, right) in the scrollbars. (2) He can move the contents 
a page or screenful at a time by pointing at the plus ( + ) and minus (-) signs. (3)He can 
jump to any arbitrary place within the entire extent of the object being viewed by pointing ^^^^ 
in the blank part of the vertical scrollbar (this latter operation is called thumbing). 

StarWindowShell provides various levels of support to a client for performing these 
scrolling operations. The client can allow StarWindowShell to do all the scrolling 
functions, the client can do some of them and leave the rest to StarWindowShell, or the 
client can do all scrolling operations. Much of this decision will be based on how the client 
chooses to arrange body windows within the shell (see the section on body windows above 
and more discussion below). First, we will describe the various types of scrolling and 
scrolling procedures that a client can supply; then we will describe the default scrolling 
procedures provided by StarWindowShell. 

In the simplest (for the client) case, one body window contains the entire extent of the 
object being viewed. StarWindowShell can handle all scrolling in this case. The client 
simply defaults the scrollData parameter in the call to StarWindowSh«ll.Create. When the 
user points at an arrow, StarWindowShell moves the body window a small amount. When 
the user point at plus or minus, StarWindowShell moves the body window by one interior 
window's height. When the user thumbs, StarWindowShell will move the body window to 
an appropriate place based on its overall height. 

In a slightly more complex case, body windows are butted up against one another. When 
, the user points at an arrow, StarWindowShell moves all the body windows a small amount. 
When the user point at plus or minus, StarWindowShell moves all the body windows by 
one interior window's height. When the user thumbs, StarWindowShell moves all the body _ 
windows to an appropriate place based on the combined overall height of the body windows. 
However, in this case the client often does not have the entire extent of the object displayed 
in these body windows but rather wants to tack new body windows on each end as these 
body windows are scrolled ofT. The client can do this by providing a MoreScrollProc for the 
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shell. StarWindowSheil calls the client's MoreScrollProc whenever it runs out of body 
windows. 

In the most complex case, the client has a single body window that "just fits" (see 
SetBodyWindowJustFtts in the section on body windows), and only part of the entire object 
is displayed at any one time. The client must provide all the scrolling functions for this 
case. This means providing an ArrowScroilProc (to handle the user's pointing at the 
arrows, plus, and minus) and a ThumbScroilProc (to handle the user's thumbing). 

Of course, the client may provide its own scrolling procedures for any of the above cases, 
even the simple one, to override the type of scrolling that StarWindowSheil provides. 

ScrollData: type ■ record [ 

dispiayHortzontal: boolean <- false, 
display Vertical: boolean false, 
arrowScroll: ArrowScroilProc nil, 
thumbScroil: ThumbScroilProc nil, 
moreScroll: MoreScrolllProc <-nil ]; 

ScrollData is passed to Create and SetScrollData to specify the desired scrolling. 
dIsplayHorlzontal indicates whether the shell should have a horizontal scrollbar. 
displayVertical indicates whether the shell should have a vertical scrollbar. arrowScroll is 
called when the user points at the arrows or at the plus or minus signs. thumbScroil is 
called when the user thumbs. These procedures are expected to perform the appropriate 
scroll, probably by moving body windows with window. Slide. If either arrowScroll or 
thumbScroil are nil, StarWindowSheil provides default scrolling procedures 
(VanillaArrowScroil and VanillaThumbScroil) that operate as described above. moreScroil 
is called when VanillaArrowScroil or VanillaThumbScroil needs more body windows to be 
supplied by the client. The client should never need to supply both an arrowScroll and a 
moreScroil. 

ArrowScroilProc: type » procedure [ 
sws: Handle, 
vertical: boolean, 
flavor: ArrowFlavor, 

arrowScrollAction: ArrowScrollAction «-go]; 
ArrowFlavor: type ■ (pageFwd, pageBwd, forward, backward}; 

An ArrowScroilProc is called whenever the user points at an arrow or the plus or minus 
sign in a scrollbar. The ArrowScroilProc is expected to scroll the contents of sws as 
appropriate, vertical indicates whether to scroll vertically (true) or horizontally (false). 
flavor indicates what type of scrolling the user requested. pageFwd means the user pointed 
at the plus sign (vertical « true) or the right margin symbol (vertical ■ false). pageBwd 
means the user pointed at the minus sign (vertical ■ true) or the left margin symbol 
(vertical ■ false), forward means the user pointed at the up-pointing arrow (vertical ■ 
TRUE) or the left-pointing arrow (vertical ■ false), bacicward means the user pointed at the 
down-pointing arrow (vertical ■ true) or the right-pointing arrow (vertical a false). The 
ArrowScroilProc will be called repeatedly as long as the user has the mouse button down 
over one of the arrows, thus producing continuous scrolling. Note: 
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EnumerateBodiestnlncreasingY and EnumerateBodieslnOecreasingY are quite useful 
when scrolling body windows (see the section on body windows). 

ArrowScrol I Action: type • {start, go, stop}; 

start indicates the user just buttoned down, go indicates the user still has the button down, 
stop indicates the user just buttoned up. This allows clients to scroll body windows without 
repainting until the ArrowScrollProc is called with arrowScroi I Action ■ stop. 

ThumbScroilProc: type « procedure [ 
sws: Handle, vertical: boolean, flavor: ThumbFtavor, m, outOfN: integer]; 

ThumbFtavor: type a {downClick, trade, upOicic}; 

A ThumbScroilProc is called whenever the user points in the thumbing part of the vertical 
scrollbar, vertical is always true (horizontal thumbing is not currently allowed), flavor 
indicates whether the user has just buttoned down (downClick), is moving the mouse with 
the button down (track), or has just released the button (upGIck). Usually, the actual 
scrolling does not take place until the upClick. downClick and track give the client an 
opportunity to display information to the user, such as what page number the current 
cursor location corresponds to (see Cunor.NumberlntoCursor). m and outOfN indicate 
where the cursor is with respect to the entire extent of the thumbing area. For example, if 
m = 200 and outOfN = 400, the user wants to thumb to the middle of the entire object. 
Note: EnumerateBodiestnlncreasingY and EnumerateBodieslnOecreasingY are quite 
useful when scrolling body windows (see the section on body windows). 

PaintThumbFeedBack: proc[sws: Handle, offset: Percent, portion: Percent «~0]; 

EraseThumbFeedBack: proc[sws: Handle]; 

GetScrollbar: PROC [sws:Handle, vertical: boolean true] returns [window.Handlej; 
Percent: TYPE m integer (0.. 100]; 

PaintThumbFeedback, etc. support the painting of feedback into the thumbing region of a 
scrollbar. These items are defined in Star WindowShell£xtra3. mesa. 

PercentOf : proc [v: integer, p: Percent] returns [integer]; 

PercentOf expresses p in terms of v. For example, m «- PercentOf [OutOfN, offset] . 
Percentage: proc [part, full: integer] returns [Percent]; 

Percentage returns the percentage of part to full. For example, offset Percentage[m, 
OutOfN]. 

PaintThumbFeedback, etc. support the painting of feedback into the thumbing region of a 
scrollbar. These items are defined in StarWindowShellExtraS.mesa. 

MoreScrollProc: type a procedure [ 
sws: Handle, vertical: boolean, flavor: MoreFlavor, amount: cardinal]; 
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MoreFlavor: type a {before, after}; 

A MoreScrollProc is called by the default StarWindowShell scrolling procedures, 
VaniilaArrowScroil and VanillaThumbScroil, whenever more body windows are needed to 
continue scrolling. This is used when the client has several body windows butted against 
one another. When the user points at an arrow, VaniiiaArrowScroli moves all the body 
windows a small amount. When the user point at plus or minus, VaniilaArrowScroil moves 
all the body windows by one interior window's height. When the user thumbs, 
VanillaThumbScroil moves all the body windows to an appropriate place based on the 
combined overall height of the body windows. However, the client often does not have the 
entire extent of the object displayed in these body windows but rather wants to tack on new 
body windows on each end as these body windows are scrolled oflT. This is when the client's 
MoreScroiiProc is called, vertical indicates whether the user was scrolling vertically or 
horizontally, flavor indicates whether to tack on more body windows before (that is, the 
user was scrolling down for vertical « true, right for vertical a false), or after (that is, the 
user was scrolling up for vertical » true, left for vertical ■ false), amount indicates how 
much extra body window is needed, in screen dots. 

The client's moreScroll procedure is responsible for adding and deleting body windows from 
the shell. The case being handled is that in which the client has a large number of pages to 
display to the user and wishes to manifest only a few. Then we need to handle the case in 
which system scrolling would make a non-manifest page visible, and there is no body 
window for it. Whenever the system is about to perform a scroll function, it checks to see if 
the scroll action would move the visible portion of the bodies off the end of the existent body 
windows. If so, it calls a non-nil client MoreScroiiProc, indicating how much more body 
window may be displayed. The client may augment the collection of body windows or not. 
The system routines will not scroll past the end of the body windows. The client may also 
use this opportunity to garbage-collect body windows that have been scrolled off the other 
end and are no longer visible. 

noScrollData: ScrollData *~ U; 

noScrollData indicates no scrollbars at ail. 

vanillaScrollOata: ScrollData «- [ 
dispiayHorizontai: false, 
display Vertical: true, 

arrowScroll: nil, ~ actua//y VaniilaArrowScroil 
thumbScroll: nil,— actua//y VanillaThumbScroil 
moreScroll: nil ]; 

vanillaScrollOata is the default for the scroll Data parameter to Create. It indicates 
avertical scrollbar with the starWindowSh«II.VanillaXXXScroll procedures described above. 

GetScrollData: procedure [sws: Handle] returns [scrollData: ScrollData]; 

GetScroilData returns the current ScrollData associated with sws. May raise Error 
[notASWS]. 

SetScrollData: procedure [sws: Handle, new: ScrollData] 
RETURNS [old: ScrollData]; 
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SetScroilOata sets the current Scroll Data for sws and returns the previous. May raise Error ^01^ 
[notASWSl. 

VanillaArrowScroll : ArrowScrollProc; 
VaniilaThumbScroil : ThumbScroilProc; 

The default scrolling procedures that StarWindowShell provides are exported here. This 
allows a client to insert its own scroll procedures, check for certain conditions that it wants 
to handle, and call StarWindowShell to do the scrolling for other conditions. 

50.2.6 Push, Pop, etc. 

The StarWindowShell returned by Create is not displayed on the screen; that is, is not 
inserted into the visible window tree. A StarWindowShell may be inserted into the window 
tree by calling Push. This is usually not done by the client but rather by some other part of 
Viewpoint, such as the desktop implementation. For example, when the user selects an 
icon and presses OPEN or PROPS, the application (actually the application's 
Contain««.GenericProc) creates a StarWindowShell and returns it. The desktop 
implementation then displays the StarWindowShell by doing a Push. 

A StarWindowShell is removed from the screen by calling Pop. Clients almost never call 
Pop. Rather, StarWindowShell calls Pop when the user selects Close, or PropertySheet 
calls Pop when the user selects Done or Cancel. 

Push allows one shell to be pushed on top of another shell, thus providing the illusion of 
"open- within." For example. Star folders and file drawers use this illusion. 
StarWindowShell has provisions for a shell to display commands in the header of the shells 
pushed on top of it. (See the section one Pushee commands.) Most clients will not make use 
of this feature of Push, because the ContainerWindow interface takes care of this for 
applications that appear as a list of items that may be opened. Fine point: We simplify things here 
by replacing the entire shell. When the shell on top is closed, the shell below still exists and is simply redisplayed. 

Push: PROCEDURE ( 

newShell: Handle, topOfStack: Handler- nil, 
poppedProc: PoppedProc 4- nil ]; 

Push displays newShell by inserting it into the visible window tree. If topOf Stack is nil, 
newShell is placed directly on the desktop. If topOf Stack is mt mi, then newShell is pushed 
on top of topOf Stack and topOfStack is removed from the display (but see the fine point 
below). If topOf Stack is not nil, it must be currently visible ( that is, does not have another 
shell Pushed on top of it). If poppedProc is not nil, it is called when newShell is Popped. The 
poppedProc must either sleep the shell or destroy the shell, usually by calling 
SleepOrDestroy. If poppedProc is nil, newShell will be destroyed when it is Popped. Note 
that Push can be called repeatedly with topOf Stack being the newShell from the previous 
call, thus producing a stack of StarWindowShells. May raise Error [notASWS]. 

Pine point: For open-within, we are experimenting with opening the newShell overlapping the topOf Stack shell, 
allowing the userto look at the container and the thing contained at the same time. This has some rather complex ^^^i 
implications with respect to having two views of the same things, being able to open several contained items at 
once, afid so forth. 
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PushedMe: procedure [pushee: Handle] returns [pusher: Handle]; 

PushedMe returns the next lower shell below pushee in the stack (nil if none). PushedMe 
is defined in Star WindowShellExtra. mesa. 

PushedOnMe: procedure [pusher: Handle] returns [pushee: Handle]; 

This procedure returns the next higher shell above pusher in the stack (nil if none). 
PushedOnMe is defined in StarWindowShellExtra.mesa. 

PoppedProc: type » procedure [popped, newShell: Handle, 
popOrSwap: PopOrSwap 4- pop]; 

PopOrSwap: type ■ {pop, swap}; 

popped is the shell that is being taken out of the visible window tree. newSheil is the shell 
that becomes visible because of popped being popped. It is nil if popped was not opened 
within another window. popOrSwap indicates the action that caused the shell to be 
popped, either StarWindowSh«il.Pop or StarWindowSheil.Swap. 

Pop: procedure [popee: Handle] returns [Handle]; 

Pop removes popee from a stack of shells and returns the shell that is now on top of the 
stack. If popee was Pushed with a poppedProc, this poppedProc is called. If popee is not 
the top of a stack, then all shells above it in the stack are Popped. May raise Error 
[notASWS]. 

Swap: procedure [ 
new. old: Handle, 
poppedProc: PoppedProc 4- nil] ; 

Swap replaces old, which must be the top of a stack, with new. Equivalent to a Pop 
followed by a Push, but with a lot less screen flashing. May raise Error [notASWS]. Folder 
uses this procedure when doing a "Show Previous". 

Replace: procedure [new, old: Handle]; 

Replaces the old shell with new without calling old's PoppedProc. old's PoppedProc 
becomes the PoppedProc for new. Fine point: This procedure is currently exported through 
StarWindowSheilExtra.. TTY uses this procedure when going from the option sheet to the tty 
window. (The option sheet's MenuItemsProc calls. StarWindowShellExtra.Replace then 
returns ok » false to MenuItemsProc's caller.) 

Note that the application is responsible for destroying the extra shell, since the 
PoppedProc (when it does eventually get called) will destroy only the shell actually 
being popped. Thus, in general, the application should call SWS. Destroy on the psheet 
shell sometime after doing the Replace. 



50.2.7 Limit and Adjust Procs 

Limit and Adjust procs are client-supplied procedures that allow a client to get control 
whenever a StarWindowShell is going to change size or location. A LimitProc gives the 
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client control over the size and placement of a shell. An AdjustProc gives the client an 0Kl^ 
opportunity to fix up the data structures and display for the shell's body window(s). ^ 

LimitProc: type ■ procedure [sws: Handle, box: window.Box] returns [window. Box]; 

GetLimitProc: procedure [sws: Handle] returns [LimitProc]; 

SetLimitProc: procedure [sws: Handle, proc: LimitProc] RETURNS [old: LimitProc]; 

Whenever the size or location of a shell is going to change, the client's LimitProc is called. 
This allows the client to exercise veto or modification rights over the size and location of a 
StarWindowSheil. This is useful, for example, to prohibit a shell from becoming smaller 
than some certain size or from being moved completely off the screen, box is the requested 
size of the shell. The LimitProc should return the desired size of the shell. The LimitProc is 
called before the AdjustProc. The interior box of the shell box returned by the LimitProc is 
passed to the AdjustProc. GetLimitProc and SetLimitProc may raise Error [notASWS]. 

-StandardLimitProc: LimitProc; 

A StandardLimitProc is provided that keeps shells on the screen and keeps them from 
getting too small. 

AdjustProc: type » procedure [sws: Handle, box: window.Box, when: When]; 

When: type » {before, after}; ^/^^ 

GetAdjustProc: procedure [sws: Handle] returns [AdjustProc]; 

SetAdjustProc: procedure [sws: Handle, proc: AdjustProc] RETURNS [old: AdjustProc]; 

The AdjustProc is called whenever the shell is going to change size. It is called both before 
and after the window's size is changed. The box passed to the AdjustProc is the interior 
window's box (the client's viewing region in the shell). The when parameter indicates 
whether the current call is before or after the window's size has been changed. An 
AdjustProc is for those clients whose body window display depends on the size of the 
surrounding shell. For example, if the body window sticks out of the interior of the shell 
and the user must scroll the body window horizontally to see all the contents, then no 
AdjustProc is needed. If, on the other hand, the content of the body window is always kept 
visible regardless of the size of the shell (by wrapping the contents around as in the Tajo 
FileWindow editor), then the client needs an AdjustProc. GetAdjustProc and SetAdjustProc 
may raise Error [notASWS). 

50.2.8 Displayed StarWindowShells 

EnumerateOisplayed: procedure [proc: ShellEnumProc] returns [Handle [nil]]; 

EnumerateOispiayedOfType: procedure [SheliType, proc: ShellEnumProc] 
RETURNS [Handle 4- [NIL]]; 

EnumerateMyOisplayedParasites: [sws: Handle, proc: ShellEnumProc] 
RETURNS [Handle [nil)]; 
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SheilEnumProc: type « procedure [victim: Window.Handle] 

RETURNS [stop: BOOLEAN false]; 

These procedures enumerate visible StarWindowShelis. Each one returns the last shell 
incurred in the enumeration if the SheilEnumProc returns true; otherwise, they return nil. 
EnumerateMyOisplayedParasites may raise Error [notASWS]. 

30.2.9 Errors 

Error: ERROR(code: ErrorCode]; 

ErrorCode: type ■ {deslctopNotUp, notASWS, notStarStyie.tooManyWindows}; 



50.3 Usage/Examples 

30.3.1 Example 1 

— Create a StarWindowSheli - simple case 

CreateSheil : procedure returns [starWindowSh«ii.Handle] ■ 
BEGIN 

another: xstrmg.ReaderBody <-xstring.FromSTRlNG[*'Another"L]; 
repaint: xstring.ReaderBody 4-xstring.FromSTRING[**Repaint''L]; 
post: xstring.ReaderBody <-xstrmg.FromSTRING("Post A Message "L]; 
sampieTooi: xstring.ReaderBody ^xstring.FromSTRINGCSampie Tool"L]; 

- Create the StarWindowSheli 

- Note: Since a zone was not supplied, one will be created (and destroyed) for you. 
shell: starWindowSheiLHandle m starWindowSheiUCreate [name: @sampleTool]; 

— Create a body window inside the StarWindowSheil 
body: Window.Handle ■ starWindowSh«ii.CreateBody [ 

sws: shell, 

box: [ [0,0]« bodyWindowDims ], 
repaintProc: Redisplay. 
bodyNotifyProc: NotifyProc]; 

— Create some menu items 

z: uncounted ZONE 4- starwindowSheii-GetZone [shell]; 

items: array [0..3) of MenuOata.ltemHandle *- [ 

ManuOata.Createitem [zone: z, name: ©another, proc: MenuProc], 
MenuOata.Createltem [zone: z, name: ©repaint, proc: RepaintMenuProc], 
MenuOata.Createitem [zone: z, name: @post, proc: Post] ]; 

myMenu: Menuoata.MenuHandle > MenuOata.CreateMenu [ 
zone: z, 
title: NIL, 

^^■^ array: descriptor [items]]; 

starWindowSheiuSetReguiarCommands [sws: shell, commands: myMenu); 
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- The calling procedure will call StarWindowSheil.Push on the returned shell to make 

- the shell visible. 
RETURN [shell]; 



END; -o/CreateShell 



Example 2 



— Create a StarWindowSheil using a client supplied Zone 

There are various Heap checking tools for determining the 
~ appropriate parameters to be used when creating the Zone. 
" Performance can be dramatically affected by these parameters. 

CreateSheil :procedure returns [starWindowSh«ii.Handle] « 
BEGIN 

myZone: UNCOUNTED ZONE a Heap.Create{injtiai: 5]; 

sampleTooi: xstring.ReaderBody «-xstring.FromSTRING['*Sampie Tool"L]; 

- Create the StarWindowShell 

- Now a zone and a TransitionProc were specified. 
shell: starWindowSheii.Handle ■ StarWindowShell. Create [ 

name: ©sampleTooi, zone: myZone, transitionProc: IVIy TransitionProc]; 

— Afeed to define the Destroy ZoneProc so we can destroy the zone at the end. 
Since we are using Heap to create the zone, we will use 

« the OefaultDestroyZoneProc which does not examine client data, so leave it NIL. 
n 4- StarWindowShellExtra5.SetOestroyZoneProc{ 
sws: shell, proc: OefaultDestroyZoneProc]; 

-- The rest of this procedure is exactly as shown in EXAMPLE 1 

END; -o/CreateSheil 

MyTransitionProc: StarWindowSheil.TransitionProc ■ 
BEGIN 

-77i#s procedure will do various tasks when the shell is Created or Destroyed. 
" It could allocate data structures (state s awake) or 

— It could deallocate data used only while the shell was open (state = sleeping). 
" It could deallocate all data created for this instance of the tool (state s dead). 
" This example handles only the destruction (state a dead) state. 

SELECT state FROM 

awake ■ > NULL; 

sleeping ■ > NULL; 

dead « > { 
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«• The zone and shell is still around. Client allowed to muck with 
" the data contained therein. For example, copy it into a file 
z: UNCOUNTED ZONE «-StarWindowSheil.GetZone(sws]; 

- Do some miscellaneous cleanup. 

- NOTE: Cannot delete the Zone - StarWindowSheil.Oestroy is not finished yet! 

}; 

ENOCASE; 

END; -o/MyTransitionProc 



30.3.3 Examples 

- Destroy the client supplied Zone in the background 

- This example does as much as possible in FORKed procedures 
-- so that the shell can be closed as fast as possible. 

« Note t/iat Process.TooManyProcesses is always handled when FORK/ng. 

CreateSheli:PROCEOURE returns [starwindowSheii.Handle] « 
BEGIN 

myZone: UNCOUNTED ZONE - Heap.Create[initiai: 5]; 

sampleTooi: xstring.ReaderBody ^xstring.FromSTRlNG['*Sample Tooi"L]; 

^•■p^ -- Create the StarWindowShell 

- A zone and a TransidonProc were specified. 
shell: starWindowSh«ii.Handte « StarWindowSheiiXreate [ 

name: @sampleTooi,zone: myZone, transitionProc: MyTransitionProc]; 

-- Oo NOT register the Destroy ZoneProc yet! 

- 77ie rest of this procedure is exactly as shown in EXAMPLE 1 
END; -o/CreateShell 

Destroy ZoneProcData: TYPE « RECORD [process: PROCESS]; 

MyTransitionProc: StarWindowShell.TransitionProc ■ 
BEGIN 

—TTifs procedure will do cleanup in the background. 
SELECT state FROM 
awake ■ > NULL; 
sleeping « > NULL; 
_j dead • > { 

- r/ie zone and shell is still around. 

- Do some miscellaneous cleanup in the background 
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clientOata: LONG POINTER TO Destroy ZoneProcOata; 
z: UNCOUNTED ZONE StarWi'ndowSheil.GetZone{sws]; 

- Do the cleanup in another process. If this is impossible, 

- then recover as gracefully as possible. 

- Do not change Process.Priority of the current (NOTIFiER) 

- process - dire results possible. 

p: PROCESS 4- FORK CIeanup(z, TRUE ! Process.TooManyProcesses ■ > { 
Oeanup{z, FALSE]; 
Heap.Delete(z]; 
EXIT}]; 

- Need to remember the process that is doing Cleanup. 
ciientData 4- z.NEW(DestroyZoneProcOata 4- [p]]; 

- Call SetOestroyZoneProc now that we have the ciientData for it. 
Q 4-StarWindowShellExtra5.SetDestroyZoneProc( 

sws, MyOestroyZoneProc, ciientData); 

}; 

ENOCASE; 

END; -o/l\4yTransitionProc 

aeanup:PROC(z: UNCOUNTED ZONE, bacicgroundOK: BOOLEAN] « 
BEGIN 

~ Do whatever cleanups are necessary. 

" Cannot delete the zone. 

- StarWindowShell is not yet finished with it. 

- If not in the NOTIFIER then ok to change priority. 

IF backgroundOK THEN Process.SetPrionty(Process.priorityBaci(ground]; 

END; " of Cleanup 

MyOestroyZoneProc: StarWindowShellExtraS.DestroyZoneProc » 
BEGIN 

- Want to return as quickly as possible so FORK the actual destroy. 

- Guaranteed that StarWindowShell is finished with the zone at 
r- this point Now it is safe to destroy the zone. 
Process.Detach[ 

FORK DoDestroylnBaci(ground[z, ciientData, TRUE 
! Process.TooManyProcesses ■ > { 

DoOestroyinBackground[z, ciientData. FALSE]; 
CONTINUE}]]; 

END; of My Destroy ZoneProc 
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OoOestroylnBackground: PROC [z: UNCOUNTED ZONE, clientOata: LONG POINTER TO 

DestroyZoneProcOata, backgroundOK: BOOLEAN] * 

BEGIN 

- Grab my data out of heap before deleting it. 

- This is where t stored the Cleanup process, 
destroyZoneProcOata: OestroyZoneProcOata ■ clientOata | ; 

- If not in the NOTIFIER then ok to change priority. 

IF backgroundOK THEN Process.SetPriority(Process.priorityBackground]; 

- Wait until Cleanup process is done with zone 
JOINdestroyZoneProcData.process; 

- Now delete the zone. 
. Heap.Oelete[z]; 

END; -o/DoDestroylnBackground 
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50.4 Index of Interface Items 



Item 


Page 


Item 


Page 


AddPopupMenu : procedure 


14 


GetState: procedure 


16 


AddPopupMenuX: PROCEDURE 


14 


GetTransitionProc: procedure 


16 


AdjustProc: type 


22 


GetType: procedure 


8 


ArrowFlavor: type 


18 


GetZone: procedure 


8 


ArrowScroii Action: type 


18 


Handle: type 


6 


ArrowScroliProc: type 


18 


HaveOispiayedParasite: procedure 


9 


BitmapUnderOption: type 


6 


InstaliBody: procedure 


12 


BodyEnumProc: type 


11 


IsBodyWindowOutOf Interior: procedure 


11 


Create: procedure 


4 


IsCloseLegai: procedure 


8 


CreateBody: procedure 


10 


isCloseLegaiProc: type 


6 


CreateWithBitmapUnderOption: procedure 


6 


IsCloseLegalProcReturnsFalse: procedure 


3 


OefaultOestroyZoneProc: OastroyZoneProc 


8 


LimitProc: type 


22 


OestallBody: procedure 


12 


ManagerFromSheli: procedure 


7 


Destroy: procedure 


6 


MenuEnumProc: type 


13 


OestroyBody: procedure 


10 


MoreFlavor: type 


19 


OestroyZoneProc: procedure 


7 


MoreScrollProc: type 


19 


EnumerateAilMenus: procedure 


15 


NewStandardCloseEverything: procedure 


7 


EnumerateBodiestnDecreasingY: procedure 


11 


noScroilData: Scroll Data 


20 


EnumerateBodiesinincreasingY: procedure 


11 


nullHandle: Handle 


6 


EnumerateOispiayed: procedure 


23 


PaintThumbFeedBack: procedure 


19 


EnumerateOisplayedMenus: procedure 


15 


Percent:TYPE 




EnumerateOisplayedOfType: procedure 


23 


Percentage: procedure 




EnumerateMyOispiayedParasites: procedure 


23 


PercentOf : procedure 


19 


EnumeratePopupMenus: procedure 


15 


Pop: PROCEDURE 


22 


EraseThumbFeedBack: procedure 


19 


PopOrSwvap:TYPE 


21 


Error: error 


23 


PoppedProc: type 


21 


ErrorCode: type 


23 


Push: PROCEDURE 


21 


GetAdjustProc: procedure 


22 


PushedMe: procedure 


21 


GetAvailabieBodyWindowOims: procedure 


11 


PushedOnMe: procedure 


21 


GetBody: procedure 


10 


Replace: procedure 


22 


GetBodyWindowJustFits: procedure 


11 


ScroilData: type 


17 


GeKontainee: procedure 


8 


SetAdjustProc: procedure 


23 


GetOestroyZoneProc: procedure 


7 


SetBodyWindowJustFlts: procedure 


11 


GetHost: procedure 


8 


SetBottomPusheeCommands: procedure 


15 


GetlsCloseLegalProc: procedure 


8 


SetContainee: procedure 


9 


GetLimitProc: procedure 


22 


SetDestroyZoneProc: procedure 


7 


GetName: procedure 


9 


SetHost: procedure 


9 


GetPreferredOims: procedure 


7 


SetlsCIoseLegaiProc: procedure 


8 


GetPreferredPiace: procedure 


7 


SetLlmitProc: procedure 


22 


GetPusheeCommands: procedure 


14 


SetMiddlePusheeCommands: procedure 


16 


GeiReadonly: procedure 


8 


SetName: procedure 


9 


GetReguiarCommands: procedure 


14 


SetNamePicture: procedure 


9 


GetScrollBar: procedure 


19 


SetPreferredOlms: procedure 


7 


GetScrollData: procedure 


20 


SetPref erredl nteri orOi ms : procedure 




GetSleeps: procedure 


16 


SetPreferredPlace: procedure 
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Item 


Page 


SetReadOniy: procedure 


10 


SetRegularCommands: procedure 


14 


SetScrollOata: procedure 


21 


SetSieeps: procedure 


10 


SetState: procedure 


18 


SetTopPusheeCommands: procedure 


16 


SetTransitionProc: procedure 


17 


SheilEnumProc: type 


23 


ShellFromChiid: procedure 


12 


SheilType: type 


8 


SieepOrOestroy: procedure 


18 


StandardClose: procedure 


8 


StandardQoseAil: procedure 


8 


StandardC!ose£verything: procedure 


8 


StandardLimitProc: LimitProc 


24 


State: type 


17 


SubtractPopupMenu: procedure 


14 


SubtractPopupMenuX: procedure 


14 


Swap: procedure 


23 


ThumbFlavor: type 


20 


ThumbScroilProc: type 


20 


TransitionProc: type 


17 


VanillaArrowScroll : ArrowScroilProc 


22 


vaniiiaScroliData: Scroll Data 


21 


VaniilaThumbScroli: ThumbScroilProc 


22 


When: type 


24 
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51.1 Overview 

The subwindow package provides a facility that clients can use to incorporate subwindows 
into their applications. We provide the capability to make subwindows scrollable 
horizontally, vertically or both, adjustable horizontally, vertically or both, moveable, and 
top/bottomable. The initial version includes the implementation of three specific types of 
subwindows: form subwindows, message subwindows and body subwindows. This allows a 
client to incorporate a form subwindow (etc.) Into an application. A facility to allow client 
defined subwindow types is also provided. Two levels of use of subwindows are supported. 
Clients can subdivide a shell and expect the subwindows to adjust in harmony with each 
other or alternately, place a subwindow in an isolated environment unrelated to any other 
subwindow. 

The interfaces that make up the subwindow package will be described here in terms of 
typical usage starting with the most common use and working down to the least common. 
Details about the various interfaces can be found in the individual chapters. The 
interfaces are: Subwindower, StarWindowShellExtraS, SubwindowiVIanager, 
SubwindowFriends, Adjustable Window, Scrollbar, Body WindowParent. 

51.2 Summary of Interfaces 

This is a brief description from the highest level interfaces to the lowest. We propose that 
Subwindower and StarWindowShellExtraS are the only truly public interfaces. The rest 
are friends. 

Subwindower 

Highest level interface, real easy to use. Given a window, it allows the predefined types of 
subwindows to be created inside it, such as FormWindows, MessageWindows, 
BodyWindows. Subwindower is a tiny impl that uses SubwindowManager and existing 
interfaces like Form Window and Message Window. 

StarWindowShellExtraS 

Given a shell, gfives you back the window that can be passed to Subwindower as the 
swmanager. It 'just-fits' inside the shell viewing region and adjusts subwindows properly 
when the shell is adjusted, etc. 
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SubwindowManager 

Provides the basic subwindow manager functions, e.g. Creating subwindows, adding and 
removing subwindows, enumerating them, adjustment UI, etc. Subwindower uses it to 
create the predefined types. 

SubwindowFriends 

Provides for client defined subwindow types. For example, FormWindow calls in to 
register its adjust procs etc to manage form subwindows. Clients can register their own 
types. 

BodyWindowParent 

Predefined subwindow type. Exports CreateBody, GarbageCollectBodiesProc, etc. 
analagous to StarWindowShell, but the whole assembly (body windows, parent clipping 
window, scrollbars, etc.) is a subwindow. Form Windows as subwindows use this. 

Adjustable Window 

Makes an arbitrary window become shrinkable, growable, moveable by the user (client has 
all sorts of options). Used by SubwindowManager. This is where AdjustProc and 
LimitProc are defined. 



Scrollbar 

For attaching scrollbars to a window. Client supplies several scroll procs. Used by 
Predefined types. 




Subwindow Interface Compile time Dependencies 
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SubwindowerlmpI 



SubwindowManagerimpi 




i OtherUniqueTypes 
j OtherUniqueTypes 
OtherUniqueTypes 



BodyWindowParentlmpI 



MessageWi ndowl m pi 



FormWindowlmpl 




AdjustabieWindowimpi SubwindowFriendslmpi 



Scrollbarlmpl 



Subwindow imp! Dependencies 



51.3 Subdividing a Shell 

A client can easily divide a shell into subwindows that will adjust in harmony with each 
other. A subwindow may only grow as big as its neighbors minimum height will allow or 
as small as its own minimum height restrictions. It is expected that most clients of 
subwindows will require only the procedures described in §51.3. 1. 



31.3.1 Creating Predefined SWs 



The great majority of clients will be interested in dividing a shell into several subwindows 
that resize in a coordinated manner. The following code segment divides a shell into a 
message subwindow, form subwindow and a body subwindow. The message window in this 
example does not have a horizontal scrollbar. 

CreateMyTooiWindow: PROCEDURE » { 
myTool: XString.ReaderBody 4- XString.FromSTRINGC'My Tool''L]; 

—create a shell without scrollbars 

shell : StarWindowSheli.Handle <- StarWindowShei I. Create [ 
name: ©myTooU scrollData: [FALSE,FALSE.NIUNIUNIL] ]; 
z: UNCOUNTED ZONE <-StarWindowShell.GetZone [shell]; 
—get the shell's subwindow manager 

swManager: Window.Handle 4-StarWindowShellExtra5.ManagerFromSheil [ 
sws: shell]; 

%ip^ '-create an adjustable message subwindow with a vertical scrollbar only 

msgSW: Window.Handle 4-Subwindower.MakeMessageSW[ 

swmanager: swManager, size: some#, horizScroiibar: FALSE, zone: z]; 
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—create a form subwindow that is adjustable and has both scrollbars 
formSW: Window. Handle Subwindower.MakeFormSW( 

swmanager:swManager, size: some#, maiceitemsProc: Maiceltems, zone: z]; 
—create a body subwindow that is adjustable and has both scrollbars 
bodySW: Window.Handle <--Subwindower.MaiceBodySW( 

swmanager:swManager,size: some#, zone: z]; 
body: Window. Handle 4- BodyWindowParent.CreateBody[bodySW, 

displayProc: OispiayProc, notify: NotifyProc]; 
StarWindowSheii.Push [sheiil; 

}; 

A subwindow manager that just fills the available interior space in the shell is created 
automatically when you create a shell. This manager will continue to "Just fit" in the 
shells interior during subsequent resizes of the shell. Most clients are expected to use this 
manager. 

Subwindower provides the highest level facility for creating subwindows in a window. Given 
a window, it allows predefined types of subwindows to be created inside it. It is typically 
used in conjunction with starWindowSh«ilExtra5.ManagerFromSheli. Three types of 
subwindows are currently provided by Subwindow«r. They are Message Windows, 
Form Windows, and BodyWindows. More types are expected to be added later. 

A client of Subwindower. MaiceBodySW will also be interested in 
BodyWindowParant.CreateBody for creating body windows to go inside the bodyParent that is 
returned by MakeBodySW. Any number of body windows may be linked inside of the 
bodyParent. 

31.3.2 CUent Defined SWs 

Clients interested in creating their own unique subwindow type will use the 
SubwindowFriends interface. The predefined types in Subwindower are implemented this 
way. 

Clients can create their own subwindow types by using SubwindowFriends.UniqueType, 
SubwindowFri«nds.SetSWProcs and SubwindowManag«r.l\/lal(eSW. UniqueType returns a 
unique identifier that is used later by other procedures. SetSWProcs takes a unique type 
and several procedures that are to be called whenever IVlaiceSW is called with that unique 
type. IVIalceSW can be called with any uniqueType or with vanilla to create a subwindow of 
that type. A vanilla subwindow uses the standard procs provided in SubwindowFriends 
which creates a viewer with scrollbars that do simple scrolling on descendants of the 
viewer. (No descendants are provided. This is up to the client.) 

See the SubwindowManager aind SubwindowFri«nds chapters §51.3 for Sample code. 

31.3.3 Inserting and Deleting SWs 

It is possible for a client to add and subtract existing subwindows from their parent by 
using several SubwindowManager procedures. If a client wishes to create a new subwindow 
and insert it al>ove some other subwindows within the manager he can call Mal<eXXXSW 
(where XXX is Form, Message or Body) or IVIai<eSW with swmanager = FALSE (creating an orphaned 



51-4 



Viewpoint Programmer's Manual 



51 



subwindow), then at some later time call SubwindowManag«r .AppendSW, InsertSW, 
RemoveSW, or SwapSW to place it in the desired location in the swmanager. 

See the SubwindowFriends chapter §53.3 for Sample code. 

51.4 Independent SWs 

Another use of subwindows is available that allows a client to create a subwindow from 
any given window. Example: turn a Form Window windowltem into a subwindow. See 
figure 3. In this case the subwindow resize would be controlled by Form Window, If the 
user is allowed to adjust the shape of the subwindow, Form Window will adjust any other 
items in the form window to accomodate the new size of the window item/subwindow. Uses 
which do not include Form Window or swM anager will have to provide any coordination of 
resizes themselves. 

An independent subwindow may specify if it is to be moveable or top/bottomable as well as 
growable. Move, top and bottom all refer to relative location of sibling windows. In other 
words, it is possible for a client to show the user several overlapping (independent) 
subwindows. The user could move, top or bottom these subwindows with respect to one 
another in the same fashion as moving and top/bottoming shells. 

A client can create an independent subwindow by calling Adjustabiewindow.Create passing 
in the window he wishes to turn into a subwindow. Scrollbars can be added to this 
subwindow by calling S€roiibar.Attach passing scrollProcs as desired. 

51.5 Usage/Examples 

Figures 1-4 on the following pages show a number of typical subwindow configurations. 
The relevant lines of code are outlined below. 

Figure 1 (Figures 1,2 and 4 are very similar, therefore separate code is not shown for each) 
shell: StarWindowShell.Handle 4-StarWindowShell.Create [ 

name: name, scroilData: [FALSE,FALSE.NIUNILNIL] ]; 
swManager: Window.Handie StarWindowSheilExtra5.ManagerFromShell( shell]; 
msgSW: Window.Handle <-Subwindower.MakeMessageSW[ 

swmanager: swManager, size: small, zone: z]; 
formSW: Window.Handie 4- Subwindower.MakeFormSWf 

swmanager: swi\4anager, size: medium, horizScrollbar: FALSE, 

makeitemsProc: Makeltems, zone: z]; 
"the next sw might be a "uaniHa" subwindow created as follows: 
mySW: Window.Handie ^ SubwindowManager.MakeSW[ 

swmanager:swManager,size: large, zone: z]; 
•'OR To implement and use your own unique type of subwindow : 
my Type SubwindowFriends.UniqueSWTypeQ 
SubwindowFriends.SetSWProcs[myType,MyAttachScroilbarsProc]; 
mySW <~SubwindowManager.MakeSW[type: myType 

swmanager:swManager, size: large, zone: z]; 

Figure 3 

"Create a shell with a form window inside it 
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"in the MakeltemsProc create a windowltem to use for the log subwindow 
"then turn that window item into a subwindow 

"make the window item an adjustable window 

Ad j usta bi e Wi ndow. Create(wi ndowltem , WDi msChangeProc, zone, 

MyLimitProc, [FALSE JRUE,FALSE,TRUE], FALSE. FALSE]; 
"implement some variety ofAttachScrollbarsProc or call the Standard version 
SubwindowFriends.StandardAttachScrollbars[...]; 

WDimsChangeProc:AdjustableWindow.AdjustProc. • { 
SELECT when FROM after ■ > 

FormWindow.SetWindowltemSizefform, witemkey, box] } 
ENOCASE } 
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Figure 3 
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52.1 Overview 

Subwindower provides the highest level facility for creating sub windows in a window. 
Given a window, it allows predefined types of subwindows to be created inside it, e.g. 
BodyWindows, Form Windows, Message Windows. It is typically used in conjunction with 
StarWindowSh«ll.ManagerFromSheil. Fine point: in BWS 4.3, ManagarFromShcllis in starwindowShniiEMtras. 
See the chapters on FormWindow, M«ssag«Window and BodyWindowParent for the specifics on 
each type of subwindow. For a comprehensive view of all the subwindow interfaces and 
their intended use, see the Subwindow Overview chapter. 

52.2 Interface Items 

52.2.1 Making subwindows 

Three types of subwindows are currently provided by Subwindower. They are 
Message Windows, FormWindows» and Body Windows. Fine Point: more tjrpes are expected to be 
added later. Each is identical to its non-subwindow counterpart in all functional respects. 
These window types can be created using MakeFormSW, MakeMessageSW and 
MaiceBodySW described in the following sections. 

A number of parameters to each MakeXXXSW procedure are identical and are described 
here, rather than with each procedure. 

swmanager refers to the parent window that will contain the subwindow(s). (Note: a 
swmanager that manages the adjustment of adjacent subwindows may be obtained by calling 
StarWindowShetlExtra5.Manag«rPromSh«ll. ) 

size specifies the size of the subwindow (see Figure 1). If scrollbars are attached, the 
viewing region within the subwindow is reduced by the width of a vertical scrollbar. If the 
subwindow is the bottom subwindow in the swmanager it will be sized to fill any remaining 
space in the swmanager. Fine Point: If the subwindows are vertically displayed, size represents the height 
of the subwindow. If the subwindows are horizontally displayed, size represents the width of the subwindow. In 
the initial implementation (4.x) only vertically displayed subwindows are supported. 

vertScrolibar indicates whether or not a vertical scrollbar is desired. 

horizScrolibar indicates whether or not a horizontaiscrollbar is desired. (In Figure 1 the 
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message window at the top of the shell has only a vertical scrollbar. The form and lower 
subwindows have both horizontal and vertical scrollbars). 

adjustable indicates if the subwindows size is to be adjustable. 

Note that there is no '*place" parameter. Subwindows will be placed in their parent 
(swmanager) in the order in which they are created. The first subwindow is placed at [0,0], 
the next one at fIrstSize + 1 and so on. 

Fine Point: In each of the procs described here passing a NIL swmanager will return an "orphaned" subwindow. 
An orphan is a subwindow that has no parent and is not placed in a window tree. An orphan can be inserted at 
some later time using the procedures available in SubwindowManagcr. 

SZJL2 Creating Form subwindows 

MakeFormSW: proceoure( 

swmanager: window.Handle. 

size: INTEGER4- SubwindowManager.minSize. 

vertScroiibar, horizScrolibar, adjustable: boolean 4-true, 
makeitemsProc: Fonnwindow.MakeltemsProc. 

layOUtPrOC: FormWindow.LayOUtPrOC 4- NIL. 

~ uses Form WindowDefaidtLayout if NIL 

windowChangeProc: Formwindow.GlobaiChangeProc nil. 
minOimsChangeProc: FormWindow.MlnOimsChangeProc 4-nil. 

•-uaesFormWiridowjDeftiuUMinDimsChangeProeifNIL 
zone: UNCOUNTED ZONE. 

ciientData: long pointer nil] 
RETURNS (form: Window.Handle]: 

MakeFormSW creates a form subwindow. The client can specify if scrollbars are to be 
attached and if the window is to be adjustable. See §2.1 for specifics about swmanager, 
size, vertScroiibar, horizScrolibar, and adjustable. 

makeKemsProc, iayoutProc, windowChangeProc, minDimsChangeProc, zone and 
dientOata are all identical to the psu'ameters in FormWindow.Create. Refer to that chapter 
for further information. 

The RETURN parameter form is the form window itself. Note that this form window is 
inside of the viewing region of the subwindow and is a different window from the formSW. 
(See figure 1 for a pictorial representation of the formSW and its descendant form window) 
The subwindow will be of size size. It's viewing region will be a scrollbar width smaller if 
scrollbars are present. The form window will be sized to '*just fit" around all the items laid 
out within it by the iayoutProc. 
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Figure 1 

Distinguishing the subwindow from its contents: The formSW contained in the shell in the first diagram 
is shown alone in the second diagram. The ghosted portions represent the hidden parts of the underlying 
form window. The formSW is shown to be sized such that only a small portion of its descendant form 
window is visible. The form is scrolled to show only the fourth item within it. 
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32.2.3 Creating Message sub windows 

MakeMessageSW: proceourec 
swmanager: window.Handle. 
size*. iNTEGER4~ SubwindowManager.minSizer 

vertScrolibar, horizScrollbar, adjustable: boolean 4-true. 

lines: CARDINAL 4- 10. 
zone: UNCOUNTED ZONE] 

RETURNS (message: vvindow.Handlei; 

MakeMessageSW creates a message subwindow. The client can specify if scrollbars are to 
be attached or the window is to be adjustable. The effect of these parameters is described 
above in §2.1. The subwindow will be of size size. The height of the message window itself 
will be based on number of lines. (Note: A message subwindow with scrollbars will be a 
scrollbar width smaller than size to account for the addition of the scrollbars.) lines and 
zone are identical to the parameters in MessageWindow.Create. Refer to that chapter for 
further information. 

52.2.4 Creating Body WindowParent subwindows 

MakeBodySW: procc 

swmanager: window.Handle, 

size: INTEGERS- SutMvindowManager.minSize, 

vertScroilbar. horizScrollbar, adjustable: boolean 4- true, 

adjuStProC: AdjustableWindow.AdjuStPrOC ^NIL. 

garbageCoilectBodiesProc: BodywindowParent.GarbageCoilectBodiesProc <- nil. 
moreScroilProc: BodywindowParant.MoreScrollProc 4-nil, 

scroi i bar! nf oProc: Scroiibar.Scrol I ba rl nf oProc *- Body windawPar«nt.Oef aui tScrol I ba rl nf o. 
thumbFeedbackProc; Scroiibar.ThumbFeedbackProc <-nil, 

thum bScroiiProc: Scroiibar.Th um bScrol I Proc *^ Body windowParent.Oef a u I tTh u m bScro II . 

zone: UNCOUNTED ZONE] 

RETURNS (bodyParent: window.Handle|: 

MakeBodySW creates a bodyParent window that is a descendant of swmanager. 
swmanager, vertScroilbar, horizScrollbar, and adjustable are described in detail in §2.1 of 
this chapter. See the Body WindowParent chapter for information about adjustProc, 
scroll bad nfoProCr moreScroilProc, garbageCollectBodiesProc, . thumbFeedbackProc, 
thumbScrollProc and zone. 

The ElETURN parameter bodyParent is the bodySW itself NOT an individual "body" 
window. The client is expected to place a body or bodies inside the bodyParent window by 
calls to BodyWindowParent.CreateBody. For example, a bodyParent without bodies is 
uninteresting. Refer to the Body WindowParent chapter for further information regarding 
the relationship between a bodyParent and body windows. 
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Figure 2 

Tool produced by the Sample Code in §3 
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52.3 Usage/Examples 

CreateMyToolWindow: PROCEDURE a { 
myTool: XString.ReaderBody *-XString.FromSTRING("My Toori]; 
shell: StarWIndowSheil.Handle 4- StarWindowShell.Create [ 

name: ©myTool, scrollData: [FALSE,FALSE,NIUNIL,NIL] ]; 
z: UNCOUNTED ZONE 4- StarWindowSheil.GetZone [shell]; 
swManager: Window.Handle StarWindowShellExtra5.ManagerFromShell[ 

sws: shell]; 
-establish some initial window heights 
shelldims: Window.Dims *~ [375, 400] 
minimum: INTEGER 20; 
small: INTEGER 60; 
medium: INTEGER ^ 300; 
bodyBox: Window.Box [[0,0],/naml}/e]; 
msgSW: Window.Handle Subwindower.MakeMessageSW[ 

swmanager: swManager, size: minimum, horizScrollbar: FALSE, zone: z]; 
formSW: Window.Handle Subwindower.Mai(eFormSW[ 

swmanager:swManager, size: small, makeltemsProc: Maiceltems, zone: z]; 
bodySW: Window.Handle 4-Subwindower.MakeBodySW( 

swmanager:swManager,size: medium, zone: z]; 
body: Window.Handle BodyWindowParent.CreateBody[bodySW, bodyBox, 

Display Proc, Notify Proc]; 
StarWindowShell.SetPreferredlnteriorDims[shell, shelldims]; 
StarWindowShell.Push [shell]; 

}; 

DisplayProc: PROCEDURE « { 
-how does my body window display itself?- 

}; 

NotifyProc: TIP. Notify Proc ■ { 
-what is my body window interested in seeing?- 

}; 

MakeltemsProc: FormWindow.MakeltemsProc ■ { 
-make some items using FormWindow.MakeXXXltem- 

}; 
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52.4 Index of Interface Items 

Item Page 

MakeBodySW:PROCEDURE 4 

MakeFormSW:PROCEOURE 3 

MakeMessageSWiPROCEOURE 3 
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53.1 Overview 

SubwindowFriends provides a facility for registering new subwindow types. The client 
provides the various procedures that will be needed later when a subwindow of the new 
type is being created. For a comprehensive view of all the subwindow interfaces and their 
intended use, see the Subwindow Overview chapter. 

53.2 Interface Items 

53.2.1 Registering Subwindow types 

UniqueSWType: procedure 

RETURNS [SwType: SubwindowManager.SWType); 

UniqueSWType registers a client-defined subwindow type returning a unique type that is 
used later by other procedures. 

SetSWProcs : procedure [ 

type: SubwindowManager.SWTyp*. 

attachScroilbarsProc: AttachScrollbarsProc StandardAttachScrollbars, 
clientWindowFromSWProc: CHentWindowFromSWProc *- 

StandardClientWindowFromSW, 
adjustProc: Adjustable window.AdjustProc *~ StandardAdjust, 
limitProc: AdjustabieWindow.LimitProc <- StandardLimit 
transitionProc: SubwindowManager.TransitionProc 4-StandardTransition ]; 

Registers the procedures to be called by SubwindowManager.MakeSW (etc.) when creating, 
resizing or changing state of a sw of type. 

attachScroilbarsProc is called when a window of type is being created. This proc is 
expected to call S€rollbar.Attach with the proper window etc. 

clientWindowFromSWProc is called to get the client window when only the subwindow 
handle is known. 
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adjustProc is called when client subwindow of type is about to be resized (when = before) 
and again just after the resize occurs (when = after). 

limitProc is called when client subwindow of type is about to be resized. 

transitionProc is called when the state (SubwindowManager.State) of a subwindow of type is 
changing. 

AttachScroilbarsProc type » procedure [ 
subwindow: window.Handle. 
vertScroiibar, horizScrodbar: boolean, 
zone: uncounted zone] 

RETURNS [SW: Window.Handiej; 

Client provides an AttachScroilbarsProc that will be called to attach scrollbars when 
SubwindowManager.MakeSW is called. SW may be a descendant of subwindow or the same as 
subwindow. 

ClientWindowFromSWProc: TYPE » procI 
subwindow: window.Handlei 

RETURNS (SW: Window.Handlei: 
Provides a means of getting the client window when only the subwindow handle is known. 

33.2.2 Getting subwindow procs 

GetSWProcs: procedure [ 

type: SubwindowManager.iSWTypel 
RETURNS [ 

attach Scrol I barsProc: Attach Scrol I barsProc. 
ClientWindowFromSWProc: ClientWindowFromSWProc. 
adjustProc: Adjustable window. AdjustProc 
I i mitPrOC: Adjustable window. Li m i tProc. 
transitionProc: SubwindowManager.TransitionProc ].- 

Returns the procedures registered with type. 

33.2.3 Standard Procedures 

StandardAttachScrol I bars: Attach Scrol I barsProc; 

Creates a bodyParent assembly: namely a subwindow, descendant viewer and attached 
scrollbars. Adjust and scrolling behavior will be as for body windows. The subwindow 
returned is the window passed in. 

StandardClientWindowFromSW: ClientWindowFromSWProc; 

Returns the Rrst descendant window encountered at the client level (i.e. below the 
bodyParent assembly). 



53-2 



Viewpoint Programmer's Manual 



53 



StandardAdj ust: Adj ustableWi ndow.Adj ustProc; 
Adjusts the subwindow's descendant viewer and scrollbars. 
StandardLimit:AdjustableWindow.LimitProc; 
Prevents shrinking the subwindow below minSize. 
StandardTransition: SubwindowManager.TransitionProc; 
NoOp. 

33.2.4 Errors 

Error: error [code: ErrorCode]; 

ErrorCode: type » {noSuchType, tooManyTypes, other}; 

noSuchTy pe raised if GetSWProcs or SetSWProcs are called with an invalid type 
tooManyTypes raised if UniqueSWType has been called too many times 
other not currently used 

53.3 Usage/Examples 

< <Simple code to create a tool with a new subwindow type > > 
CreateMyToolWindow: PROCEDURE « { 

myTool: XString.ReaderBody ^ XString.FromSTRING("My Toor'L]; 
shell: StarWindowShell.Handle <~StarWindowShell.Create [ 

name: (gmyTool.scrollOata: [FALSE,FALSE,NiUJMIUNIL] ]; 
z: UNCOUNTED ZONE StarWindowShell.GetZone [shell]; 
swManager: Window.Handle 4~StarWlndowShellExtra5.ManagerFromShell [ 

sws: shell]; 
"establish window heig/its 
medium: INTEGER *~ 60; 
large: INTEGER 4-300; 

formSW: Window.Handle Subwmdower.MakeFormSW[ 

swmanager: swManager, size: medium] malceltemsProc: Makeitems, zone: z]; 

mySW: Window.Handle <-SubwindowManager.MakeSW[ 
swmanager:swManager, type: myType, size: large, zone: z]; 

StarWindowSheiLPush [shell]; 

}; 



53 



Subwindow Friends 



ScrollSW: SubwindowFriends.AttachScroilbarsProc » { 
"Call Scrollbar. Attach with the desired interior window etc. 
}; 

MyWindow: SubwindowFriends.ClientWindowFromSWProc « { 

"return the same window as ScrollSW given the same subwindow 

}; 

AdjustProc : AdjustableWindow-AdjustProc ■ { 

"adjusts itself and calls Scrollbar.Adjust with the proper interior window 
ii 

LimitProc: AdjustabieWindow.LimitProc ■ { 

"impose any desired Limits 

"prudent to call SubwindowFriends.StandardLimitProc to prevent shrinking 
"below SubwindowManager.minSUe. 

}; 

TransitionProc: SubwindowManager.TransitionProc » { 

"do whatever actions are specific to myType subwindow at various state changes 
}: 

"Mainline Code 
"Create a unique type 

myType: SubwindowManager.SWType *- SubwindowFriends.UniqueSWType{]; 

"Set the procs needed for myType subwindow ( can default to Standard ones) 

SubwindowFriends.SetSWProcsftype: myType, 

attachScroilbarsProc: ScrollSW, dientWindowFromSWProc: MyWindow, 
adjustProc: AdjustProc, limitProc: LimitProc, transitionProc: TransitionProc]; 
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53.4 Index of Interface Items 



Item Page 

AttachScroiibarsProc: type 2 

QientWindowFromSWProc: type 2 

Error 2 

ErrorCode: type 2 

GetSWProcs: procedure 2 

SetSWProcs:PROCEDURE 1 

StandardAttachScroilbars: AttachScroilbarsProc 2 

StandardClientWindowFromSW: ClientWindowFromSWProc 2 

StandardAdjust: Ad justabte window. Ad justProc 2 

StandardUmit:AdjustabieWindow.LimitProc 2 

StandardTransition: SubwindowManager.TransitionProc 2 

UnjqueSWType:PROCEOURE 1 
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54.1 Overview 

SubwindowManager provides a facility for creating subwindows in a window. It is 
typically used in conjunction with StarWindowShell.M anagerFromSheil. Fine point: in BWS 
4.3, ManagerFromShell is in StarWindowShellEztra6. New types of Subwindows may be defined 
using SubwindowFriends and then an instance of that subwindow created using 
SubwindowManager. Procedures for adding and removing subwindows from their parent 
are also provided. Fine point: Predefined types of subwindows (form, message, body) can be created using the 
procedures in Subwindower instead. See the Subwindow Overview Chapter for a more complete 
look at the appropriate use for the various subwindow interfaces. 

54.2 Interface Items 

54.2.1 Making Subwindows 

MakeSW: procedure ( 

swmanager: window.Handie «-nil. 
type: SWType <- vanilla, 
size: INTEGER minSize, 

vertScroilbar, horlzScrollbar, adjustable: boolean 4-true. 
zone: UNCOUNTED zone ] 
returns [sw: window.Handle]: 

Creates a subwindow of type and size, sw is appended after the last subwindow in 
swmanager. While it is the bottom subwindow its size will be adjusted to fill the 
remaining space in its parent swmanager. If swmanager is nil, MakeSW creates an 
orphan subwindow that can be added to a swmanager at a later time using AppendSW or 
InsertSW as described below in §2.2. 

swmanager refers to the parent window that will contain the subwindow. (Note: a swmanager 
that manages the adjustment of adjacent subwindows may be created by calling 
StarWindowSh«liExtra5.ManagerFromSh«ll.) If swmanager is not already a subwindow manager, 
it will become one. 

type may be one of the predefinded types (body, form, message etc.) or a client defined 

type. Fine Point: see SubwindowFriends for creating client defined types. Currently there are 
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accelerators available to create some of the predefined types. (See Subwindower) More ^0%, 
will be implemented in the future. Most clients will use the accelerator procs to create 
these predefined types rather than MakeSW. MakeSW only creates the subwindow with 
appropriately attached scrollbars, it does NOT make the client call to FormWindow, 
Message Window, etc. See the Subwindower Chapter for more information. 

size specifies the size of the subwindow (see Figure 1). If scrollbars are attached, the 
viewing region within the subwindow is reduced by the width of a vertical scrollbar. If the 
subwindow is the bottom subwindow in the swmanager it will be sized to fill any remaining 
space in the swmanager. Fine Point: If the aubwindows are vertically displayed, size represents the height 
of the subwindow. If the subwindows are horizontally displayed, size represents the width of the subwindow. In 
the initial implementation (4.z) only vertically displayed subwindows are supported. 

vertScroilbar Indicates whether or not a vertical scrollbar is desired. 

horizScrolibar indicates whether or not a horizontalscrollbar is desired. (In Figure 1 the 
message subwindow has only a vertical scrollbar while the other two subwindows have 
both vertical and horizontal scrollbars.) 

adjustable indicates if the subwindow's size is to be adjustable. 

Note that there is no "place" parameter. Subwindows will be placed in their parent 
(swmanager) in the order in which they are created. The first subwindow is placed at [0,0], 
the next one at firstSize + 1 and so on. 

SWType: type » machine dependent { 

vanilla, body, form, message, container, log, text, list, Iast(377B)}; 

Enumerated for SWType. Fine Point: Four of the enumerated types of subwindows are currently 
implemented in 4.x. They are body, form, and message and vanilla. More of the predefined types are expected to 
be implemented later. 

GetType: PROCEDURE [ 

sw: window.Handlei 
RETURNS (type: SWTypel: 

Returns the SWType associated with sw. Can raise £rror(notASubwindowi. 

minSize: INTEGER; 

Minimum size for a subwindow. Used as the default for size in MakeSW. 

54.2.2 Adding and removing subwindows 

In the following procedures there is a common reference to sw and swmanager. These are 
described here rather than with each procedure. Each can raise Error(notASubwindow] or 
Error(notAswmanager]. The visual effects of any of these procedures will not take place 
until SubwindowManager.Repaint is called. Repaint is also described in this section. ^tUi^ 

sw refers to a subwindow that has been created using MakeSW described above or one of 
the MakeXXXSW procedures in Subwindowvr. 
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swmanager refers to the parent window that will contain the subwindow. (See §54.2.1). 

AppendSW: procI 

sw, swmanager: window.Handle, 
after: window.Handle <-nilI: 

Adds an existing sw to the swmanager after after (y=: afterPlace.y+ after Dims.h) or after 
the bottom subwindow in swmanager if after « NIL. Any subwindows below it will move 
down to allow space for the new subwindow. It is possible that they may become totally or 
partially obscured by the parent swmanager. 

InsertSW: proc [ 

swr swmanager: window.Handte, 
before: Window.Handle 4-NiLi; 

Adds sw to the swmanager before before or at the top (y=0) of the subwmanager if 
before « NIL. Any subwindows below it will move down to allow space for the new 
subwindow. It is possible that they may become totally or partially obscured by the parent 
swmanager. 

RemaveSW: PROC[ 

sw, swmanager: window.Handle]; 

Removes sw from the tree of swmanager. Adjusts the location of any other subwindows in 
the swmanager as necessary to refill the space left by sw. 

SwapSW: proc[ 

oidSW, newSW: window.Handle]; 

Removes oidSW from its parent inserting newSW in its place in the tree. newSW will 
occupy the same location and size as oldSW. 

ResizeSW:PROCEDURE [ 
SW: Window.Handle. 

size: INTEGER] 

RETURNS [Window.DimSj: 

Allows the client to programmatically change the size of a subwindow. Returns the actual 
size used for the resize after the appropriate limitProcs are called. This proc is particularly 
useful to the client who wishes to redistribute the space when adding or subtracting 
subwindows. 

Repaint: procedure [ 

swmanager: window.Handlel; 

If the swmanager is displayed. Repaint MUST be called in conjunction with any of the 
previous procedures: AppendSW, InsertSW, RemoveSW, SwapSW, and ResizeSW. This 
allows the client to make several calls to resize, add or delete subwindows before validating 
the changes. 
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54.2.3 Adjust, Limit, Transition Types and Procs 

State: TYPE a MACHINE DEPENDENT {awake(O), Sleeping, dead, iast(7)}; 

A window is always in one of three states: 
awake: displayed 
sieepi ng : created but not displayed 
dead : being destroyed 

TransitionProc: type « proc [window: Window.Handle, state: State]; 

A TransitionProc is a client-supplied procedure responsible for allocating or deallocating 
client data structures when the window's state changes, state is the new state of the 
window. 

Please note that most clients will have no need for the next 3 procedures. 
Transition: TransitionProc; 

Transition is the TransistionProc associated with the SubwindowManager window. 
Adjust: AdjustableWlndow.AdjustProc; 

An AdjustProc is a client-supplied procedure that is called every time the window is 
changing size. Adjust is the AdjustProc associated with the SubwindowManager window. 
It is to be called whenever the manager is adjusted. For example, the StarWindowShell 
adjust code calls SubwindowManager.Ad]ust[shellsSWmanager] when the shell is being 
resized. 

Li m it: Ad] usta bl e Wi ndo w. Li m i tProc ; 

A LimitProc is a client-supplied procedure that is called every time the window is about to 
change size or location. This gives the client a chance to veto or change the new box before 
the adjustment actually takes place. Limit is the LimitProc associated with the 
SubwindowManager window. 



54.2.4 UtiUties 



EnumerateSWs: procedure ( 
swmanager: wfndow.Handle, 
proc: EnumSWsProc] 
RETURNS (sw: window.Handle]: 

EnumSWsProc: type » procedure [sw: window.Handle] returns {stop: boolean false] ; 

Call proc with each sw contained in swmanager. Can raise Error[notAswmanager]. The 
client may make calls to add/delete subwindows during the course of the enumeration 
without adverse effects. 

GetZone: procedure [sw: window.Handle] returns [zone: uncounted zone]; 
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Returns the zone associated with the subwindow (sw). 

IsitManager: procedure [window: window.Handle] returns [boolean]; 

Returns true if the window is a subwindow manager. 

IsttSubwindow: procedure [window: window.Handle] returns [boolean]; 

Returns true if the window is a subwindow. 

ManagerFromSW: procedure [ 
sw: Window.Handle] 
returns (swmanager: Window.Handle]; 

Return the swmanager containing sw. Returns nil if sw is orphaned. 

SubwindowFromChild: procedure [ 
window: window.Handle] 
returns [Window.Handle 4- NIL); 

Return the subwindow containing window. Returns nil if window is not a child of a 
subwindow. 

94^5 Errors 

Error: error [code: ErrorCode]: 

ErrorCode: type » {notASubwindow, notAswmanager}; 
notASubwi ndow raised if sw is not a subwindow 
notAswmanager raised if swmanager is not a swmanager 

54.3 Usage/Examples 

< <This code will create a window shell with a message subwindow, a form subwindow and a vanilla 
subwindow. It will be up to the client to then "do something interesting" with the uanilla subwindow. 
See Figure 1 for a pictorial view of the tool created by this code. > > 

OeateMyToolWindow: PROCEDURE • { 

my Tool: XString.ReaderBody XString.FromSTRING("My Toort]; 
shell: StarWindowShell.Handle 4-StarWindowSheil.Create [ 

name: @myTooi, scrollOata: [FALSE.FALSE.NIL.NIL.NIL] ]; 
z: UNCOUNTED ZONE ^ StarWindowShell.GetZone [shell]; 
swManager: Window.Handle «-StarWindowShellExtra5.ManagerFromShell [ 

sws: shell]; 
--establish initial window heights 
small: INTEGER 4- 20: 
medium: INTEGER •(-60; 
large: INTEGER 4- 300; 

msgSW: Window.Handle 4-Subwindower.MakeMessageSW[ 

swmanager: swManager, size: small] horizScrollbar: false, zone: z]; 
formSW: Window.Handle 4-Subwindower.MakeFormSW( 
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swmanager:swManager, size: medium, makeltemsProc: Maiceitems, zone: z]; 
mySW: Window.Handie *- SubwindowManager.Mai<eSW( 

swmanager:swManager,size: large, zone: z]; 
StarWindowSheiLPush [shell]; 

}; 

MakeltemsProc: FormWIndow.MakeltemsProc ■ { 
—make some items using FormWindowMakeXXXItem— 

}; 



m 



My Tool 





Unsorted 










Version Date 



2-A 



Figure 1. Tool created in sample code 
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< <The following code segments will create a window shell with a form subwindow and a body 
subwindow. The header will have and extra menu item "AddF oo "for the user to select. Selecting 
"AddFoo " will cause another form subwindow to be added at the top of the subwindows. The 
"AddFoo "command will change to "RemoveFoo "at that time. Selecting "RemoveFoo " will remove 
the new subwindow from the shell and exchange the commands in the header. > > 

fooSW: Window.Handle «-nil; 

addltem, removeltem: MenuOata.itemHandle; 

CreateMy Tool Window: procedure « { 
myTool: XString.ReaderBody XString.FronnSTRtNG("My Toori]; 
addOn: XString.ReaderBody <-XString.FfomSTRING(" Add Foo"Ll; 
remove: XString.ReaderBody XString.FromSTRING("Remove Foo'"Ll; 
sheil: StarWindowSheil.Handle StarWindowShell. Create [ 

name: @myTooi,scroilOata: [FALSE.FALSE.NiL.NiL.NiL] ]; 
z: UNCOUNTED ZONE 4- StarWIndowShelt.GetZone [sheil]; 

removeltem ^ IVIenuOata.Createitem [zone: z, name: ©remove, proc: RemoveProcj; 
addltem MenuOata.Createitem [zone: z, name: @addOn, proc: AddOnProc]; 
item: array [0..1) OF MenuOata.itemHandle <— [addltem]; 
myMenu: MenuOata.MenuHandie ■ MenuOata.CreateMenu [ 

zone: z, title: nil, array: descriptor [item]]; 
swManager: Window.Handle «~StarWindowSheilExtra5.ManagerFromSheil [ 

sws: shell]; 
—establish initial window heights 
medium: INTEGER 60; 
large: INTEGER 4- 300; 

formSW: Window.Handle Subwindower.MakeFormSW[ 

swmanager: swManager, size: medium] makeltemsProc: Malceltems, zone: z]; 
bodySW: Window.Handle <-Subwindower.MakeBodySW( 

swmanager:swManager, size:largel zone: z]; 
body: Window.Handle <~ BodyWindowParent.CreateBody[ 

bodySW, displayProc: DisplayProc, notify: NotifyProcj; 
—create an orphan FormSW of minimum dimensions 
fooSW 4- Subwindower.MakeFormSW( 

makeltemsProc: MakeNewltems, zone:z]; 
StarWindowSheil.SetRegularCommands [sws: shell, commands: myMenu]; 
StarWindowShelLPush [shell] }; 

AddOnProc: MenuOata.MenuProc ■ { 
—add my type subwindow at the top of the sheil 
SubwindowManager.lnsertSW(fooSW, swManager]; 

"Swap the menu items 

MenuOata.Swapltem[old:addltem, new: Removeltem] }; 



RemoveProc: MenuOata.MenuProc » { 
—remove my type subwindow from the top of the shell 
SubwindowManager.RemoveSW[fooSW, swManager]; 
"Swap the menu items 

MenuOata.Swapltem(old: removeltem, new: addltem] }; 
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54.4 Index of Interface Items ^^Km^ 
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Adjust: Adjustabi«Window.AdjustProc 
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Transition: TransitionProc 


4 


TransitionProc: type * procedure 
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55.1 Overview 

TIP provides basic user input facilities through a flexible mechanism that translates 
hardware-level actions from the keyboard and mouse into higher-level client action 
requests (result lists). The acronym TIP stands for terminal interface package. This 
Interface also provides the client with routines that manage the input focus, the periodic 
notifier, and the stop key. 

35.1.1 Basic Notification Mechanism 

The basic notification mechanism directs user input to one of many windows in the window 
tree. Each window has a Table and a NotifyProc. The table is a structure that translates a 
sequence of user actions into a sequence of results that are then passed to the notify 
procedure of the window. 

There are two processes that share the notification responsibilities, the Stimulus process 
and the Notifier process. The Stimulus process is a high-priority process that wakes up 
approximately 50 times a second. When it nins, it makes the cursor follow the mouse and 
watches for keybocurd keys going up or down, mouse motion, and mouse buttons going up or 
down, enqueuing these events for the Notiiier process. 

The Notifier process dequeues these events, determines which window the event is for, and 
tries to match the events in the window's table. If it finds a match in the table, it calls the 
window's notify procedure with the results specified in the table. If no match is found, it 
tries the next table in the window's chain of tables. If no match is found in any table, the 
event is discarded. 

The Notifier process is an important process. To avoid multi-process interference, some 
operations in the system are restricted to happen only in the Notifier process. Setting the 
selection is one such operation. The Notifier process is also the one most closely tied to the 
user. If an operation will take an extended time to complete, it should be forked from the 
notifier process to run in a separate process so that the Notifier process is free to respond to 
the user's actions. 
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53.1.2 Tables 

Tables provide a flexible method of translating user actions into higher-level client-defined 
actions. They are essentially large select statements in which the user's actions are 
matched against the left side of a table with a corresponding set of results on the right side. 
Left sides of tables specify triggers— changes in state of keys— auid ena6/ers— existing state of 
keys-to be matched with the user actions. Right sides of tables specify results that include 
mouse coordinates, atoms, and strings for keyboard character input. A complete syntax 
and semantics of tables are in §55.3.2 and §55.3.3. 

Tables have a user-editable filed representation that is parsed to build a runtime data 
structure for TIP. The user-editable filed representation must be in the system catalog and 
is assumed to have a file name extension of .TIP. When a table is created by calling the 
CreateTabie operation, the tip file is parsed and its runtime data structure is created. In 
addition, a compiled version of the tip file is created in a file whose name has the character 
C appended to the name of the tip file. On subsequent calls to CreateTabie, this tipc file is 
used to create the runtime data structure as long as the tip file has not been changed. By 
avoiding parsing the tip file, building the runtime data structure from the compiled file is 
much faster. 

The table parser uses a macro package that allows macros to be defined and used in writing 
tables. It is described in §55.3.7. 

Tables may be linked to form a chain of tables. The notifler process attempts to match user 
actions in the first table of the chain. If no match is found, it tries subsequent tables in the 
chain. If no match is found in any table, the user action is discarded. Clients can use the 
links of tables to build special processing on top of basic facilities. The client can write its 
own table to handle special user actions and, by linking the table to system-defined tables, 
let them handle the normal user actions. An example is in the Usage/Examples section. 
System-defined tables, which are accessable through the TIPStar interface, are described in 
Appendix A. 

55.1.3 Input Focus 

The input focus is a distinguished window that is the destination of most user actions. User 
actions may be directed either to the window with the cursor or to the input focus. Actions 
such as mouse buttons are typically sent to the window with the cursor. Most other actions, 
such as keystrokes, are usually sent to the current input focus. 

The notifler process uses either the input focus window or the cursor window to obtain a 
table and a notify procedure. Results from matching the user actions with the table are 
normally passed to the window's notify procedure. Notify procedures may also be bound 
directly with a table. In this case, results from the table go to the table's notify procedure 
instead of to the window's notify procedure. 

Clients may make a window be the current input focus and be notified when some other 
window becomes the current input focus. 
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53.1.4 Periodic Notification 

The Notifier process is important because it responds directly to the user. To avoid multi- 
process interference, some operations in the system are restricted to happen only in the 
Notifier process. The periodic notification mechanism allows operations to happen within 
the Notifier process while the user is idle. A periodic notifier is created with a window, 
some results, and a time interval. The window's notify procedure is called with the results 
every time interval as long as the Notifier process is not processing user actions. 

55.1.3 Call-Back Notification and Setting the Manager 

Call-back notification and setting of the manager bypass the normal means of selecting a 
window as the destination of input and allow the client to receive all input. It is useful for 
something like mouse tracking when a menu is posted. This must be done only from the 
Notifier process. 

Call-back notification is so named because the client calls back to the Notifier process with 
a special call-back notification procedure, a window and a table. The Notifier matches user 
actions with the table and sends the results to the call-back notify procedure. It continues 
to do this until the call-back notify procedure says it is done. User actions that are not 
matched are discarded. 

Setting the manager makes the Notifier process use the manager's table for matching user 
actions and send the results to the manager's notify procedure. User actions that are not 
matched are discarded. 

While both call-back notification and setting the manager results in all notifications being 
sent to a single place, they are different in the control structure. With call-back 
notification, the client's call stack is not unwound, while setting the manager does not take 
effect until the current notification is processed and its call stack unwound. 

55.1.6 Attention and User Abort 

While most notifications are sent to notify procedures from the notifier process, there is a 
mechanism that allows asynchronous notification of the stop key. An AttentionProc may 
be set for a window that is called whenever the STOP key is depressed in that window. It is 
called from outside the notifier process as soon as the stimulus level sees the key go down. 
For those windows that do not set an AttentionProc, the system keeps a user abort flag that 
records whether the stop key was depressed. Clients may call UserAbort to check if the flag 
is set. It is cleared when any notification is sent to the window's notify procedure. 

55.1.7 Stuffing Input into a Window 

TIP provides operations that allow a client program to call the notify procedure of a window 
with results that the client constructs. StuffResults allows a client to pass an arbitrary 
results list to a window. StuffString, StuffSTRING, and StuffCharacter allow strings and 
characters to be passed to a window. 
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55.2 Interface Items 

35.2.1 Results 

Results: TYPE ■ L0N<3 POINTER TO ResultObject; 

ResuitObject: type « record ( 
next: Results, 
body: SELECTtype: *from 

atom ■ > [a: ATOM], 

bufferedChar * > null, 

coords a > [place: window.Ptacel, 

int a > [i: long INTEiSER], 

key « > [key: Key Name, downUp: OownUp], 
nop « > [], 

string ■ > [rb: xstring.ReaderBody], 
time » > [time: System.Pulses], 
enocase]; 

ATOM: type ■ Atom.ATOM; 

DownUp: type • L«veiiVK«ys.DownUp; - {down, up} 
KeyName: type • LeveiivK«ys.KeyName; 

The right side of a statement in a table is a list of results to be passed to the notify 
procedure when there is a match on the left side. Each element of this list of results is 
described by a ResultObject. The atom variant contains the atom from the table's right 
side. The place in the coords variant is relative to the window receiving the results. The 
reader body of the string variant is either from the bufferedChar results or from a string 
constant in the table. The pulses of the time variant is the value of System. GetPulses at the 
time the event actually occurred. 

Character input is buffered by the Notifier process. If the result of a match is a 
bufTeredChar, the Notifier process buffers the character and proceeds to try and match the 
next user actions. If there are no more user actions and the buffer of character input is not 
empty, the Notifier process calls the notify procedure with the buffered character input. If 
the next action produces a result that is not another character input, the Notifier process 
calls the notify procedure with the buffered character input and then call it with the new 
result. If the notifier process gets behind the user and a lot of character input actions get 
queued up, it collects them and passes them together to the client instead of one at at time. 

KeyName is an enumerated that describes the keyboard and mouse buttons. See the Pilot 
Programmer's Manual (610E00160) for a complete list of the elements. 



55.2.2 Notify Procedure 

NotifyProc: type ■ procedure [window: window.Handle, results: Results]; 

A NotifyProc is the means of notifying a window of user input. The parameters are the 
window that is receiving the input and the list of results that describe the input. Normally, 
the results are from the tip table associated with the window. Notify procedures may also 
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be bound directly with a table. In this case, results from the table go to the table's notify 
procedure instead of to the window's notify procedure. 

35.2.3 TIP Tables 

Table: TYPE ■ long pointer to TableObject; 
TableObject: type; 

Table is a pointer to the internal representation of a table. 
GetTableLink: procedure [from: Table] returns [to: Table]; 
SetTabieLink: procedure [from, to: Table] returns [old: Table]; 

GetTableLink and SetTabieLink allow the tables to be linked. GetTableLink returns the 
table following from in the chain, returning nil if there is no successor table. SetTabieLink 
sets the link of table from to to and returns the old value. 

SetTableOpacity: procedure [table: Table, opaque: boolean] 
returns [oldOpaque: boolean]; 

GetTableOpacity: procedure [table: Table] returns [boolean]; 

SetTableOpacity sets the opacity of table and returns the old value, while GetTableOpacity 
returns its value. If a table is opaque, then unrecognized user actions are discarded without 
searching the table chain past the opaque entry. 



55.2.4 Associating Notify Procedures, Tables, and Windows 

SetTableAndNotifyProc: procedure [ 

window: window.Handle, table: Table ^ nil, notify: NotifyProc ^ nil]; 

SetTableAndNotifyProc makes window a TIP client and associates the table and notify 
procedure with the window. If window is already a TIP client and table or notify is nil, 
then the old value is retained. 

SetTable: procedure [window: window,Handle, table: Table] returns [oldTable: Table]; 
GetTable: procedure [window: window.Handle] returns [Table]; 

SetTable sets the table associated with window to be table and returns the old table. 
GetTable returns the table associated with window. 

SetNotifyProc: procedure [window: window.Handle, notify: NotifyProc] 
returns [oldNotify: NotifyProc]; 

GetNotifyProc: procedure [window: window.Handle] returns [NotifyProc]; 
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SetNotifyProc sets the notify procedure associated with window to be notify and returns 
the old notify procedure. GetNotifyProc returns the notify procedure associated with 
window. 

SetNotifyProcForTabie: procedure [table: Table, notify: NotifyProc] 
RETURNS [oidNotify: NotifyProc]; 

GetNotifyProcFromTable: procedure [table: Table] returns [NotifyProc]; 

SetNotifyProcForTabie binds the notify procedure, notify, with table and returns the old 
value of bound notify procedure. Results from matches within the table will go to notify 
instead of to the notify procedure for the window this table is associated with. 
GetNotifyProcFromTable returns the notify procedure bound to table. 

53.2.3 Creating and Destroying Tables 

CreateTabie: procedure [ 

file: xstring.Reader, z: uncounted zone contents: xstring.Reader *~ nil] 
returns [table: Table]: 

CreateTabie generates a TIP table from the text file named by file (which may not be nil). 
file is expected to be in the system file catalog. Storage for the table will be allocated in z or 
from the implementation's zone if z is nil. contents is the default contents of file, and will 
be used if (1) the 'I boot switch is set, (2) the. file cannot be read, or (3) the signal 
InvalidTable is resumed. (See InvalidTable for further details on how to treat that signal.) 

When file is parsed, a compiled form of the table is written into a file with a name 

constructed by appending a C on the end of file. Fine Point: file should typically have the extension 

.TIP. When CreateTabie is called, if a .TIPC file exists that was created from file, the TIPC 
file is used to generate table. If the '0 boot switch is set, CreateTabie does not look for a 
.TIP file, but rather looks directly for a .TIPC file. May raise the signal InvalidTable. 

CreateCharTable: procedure [ 

z: uncounted ZONE ^NiL. buffered: boolean 4- true] returns [table: Table]; 

CreateCharTable creates a TIP table such that any down transition of any of the 
keystations (not key tops) in the main tjrping array have a right-hand side of bufferedchar. 
Storage is allocated from z if it is non-NiL or from the TIP implementation's zone. The 
boolean buffered is ignored and will be removed when this interface is updated. 

CreatePlaceHolderTable: procedure [z: uncounted zone nil] returns [table: Table]; 

CreatePlaceHolderTable creates a placeholder tip table. Placeholder tables contain no 
information themselves but allow other tables with information to be linked to them. 
Storage is allocated from z if it is non-NiLor from the TIP implementation's private zone. 

Destroy Table: procedure [long pointer to Table]; 

Destroy Table frees the table addressed by the parameter and then sets the table to nil. 
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35.2.6 Input Focus 

SetlnputFocus: proc[ 

w: window.Handie, takeslnput: boolean, newlnputFocus: LosingFocusProc <~ nil, 
dientOata: long pointer 4- nil]: 

SetlnputFocus makes the window w the input focus. If w allows type-in, takeslnput should 
be set to true; otherwise takeslnput should be set to false. newlnputFocus is called when w 
loses the input focus. It is passed dientOata as the value of its long pointer parameter. If w 
m NIL, the input focus is cleared, i.e. input focus notifications are sent to the 
backStoplnputFocus (see below). 

LosingFocusProc: type ■ procedure [w: Wlndow.Handle, data: long pointer]; 

LosingFocusProc describes the procedure type that is used to let the input focus know it is 
no longer the input focus, w is the window.Handle of the window that was the input focus, 
and data is the client data passed to SetlnputFocus. 

GednputFocus: proc returns [window.Handle]; 

GetinputFocus returns the window that currently has the input focus. 

backStoplnputFocus: readonly window.Handle; 

The window backStoplnputFocus gets all input focus notification when no other window 
requests to be the input focus. It may be nil. 

SetBackStoplnputFocus: procedure [window: window.Handle]; 

SetBackStoplnputFocus sets backStoplnputFocus, the window that gets all input focus 
notification if no other window requests to be the input focus. 

FocusTakeslnput: proc returns [boolean]; 

FocusTakeslnput returns true if the current input focus accepts input, false otherwise. 
CleartnputFocusOnMatch: proc[w: window.Handle]; 

OearlnputFocusOnMatch is used to clear the input focus in a window if that window has 
the input focus. This procedure is usually called by clients who are implementing their own 
window type when they are destroying a window. 

55.2.7 Character Translation 

CharTranslator: type ■ record [ 

proc: KeyToCharProc, data: long pointer]; 

KeyToCharProc: type « procedure [ 

keys: long pointer to KeyBits, key: KeyName, downUp: OownUp, data: long pointer, 
buffer:xstring.Writer]; 

A CharTranslator is used to construct characters from the state of the keyboard when a 
BUFFEREDCHAR result Is encountered. The KeyToCharProc is called when the notifier needs to 
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construct a character from the state of the keyboard, keys describes the current state of the 
keyboard, key and downUp describe the current character transition. The procedure 
should append the corresponding character(s) to buffer. There is a CharTranslator for each 
table. 

KeyBits: type • uv«iiVK«ys.KeyBits; 

SetCharTransiator: procedure [table: Table, new: CharTranslator] 
RETURNS [old: CharTranslator]; 

GetCharTranslator: proc [table: Table] returns [o: CharTranslator]; 

SetCharTransiator sets the character translator for table, returning the old value. 
GetCharTranslator returns the character translator for table. 



PeriodicNotify: type [1]; 
nullPeriodicNotify: PeriodicNotify; 

PeriodicNotify is a handle for a periodic notifier. Periodic notifiers are a means of notifying 
windows at regular intervals from within the Notifier. nullPeriodicNotify is the null value 
for PeriodicNotify. 

CreatePeriodicNotify: proc [ 

window: window.Handler results: Results, milliseconds: cardinal, 
notifyProc: NotifyProc«-NiLl 
returns [PeriodicNotify]; 

CreatePeriodicNotify registers a periodic notification. If notifyProc « nil then the notify 
proc associated with window is used. If notifyProc # nil, is called; this is useful if the client 
is nmning in a background process but wants to perform some operation that must be done 
in the notifier process, such as obtaining the current selection. If there is a COORDS result 
and window ■ nil , that result is [0, 0]. If notifyProc « nil and window « nil , the 
Error[other] is raised. The specified notify proc is called with parameters window and 
results once every milliseconds milliseconds as long as no user action notifications are 
taking place. If milliseconds = 0, it runs once and then destroys itself The result list 
should not contain any entries of type nop or bufferredChar. Right-hand sides of type 
coords will be adjusted to reflect the actual mouse position relative to the window being 
notified. The results list will not be copied. Its allocation is up to the client. 

CancelPeriodicNotify: proc [ 

PeriodicNotify] returns [null: PeriodicNotify]; 

CancelPeriodicNotify stops the periodic notification passed in by removing the notification 
from the list of registered procedures and returns nullPeriodicNotify. This procedure raises 
Error[noSuchPeriodicNotifier] if the handle passed in is not valid (calling it with 
nullPeriodicNotify has no effect). 



33.2.9 Call-Back Notification 

CailBack: procedure [window: window.Handle, table: Table, notify: CailBackNotifyProc]; 



33.2.8 Periodic Notification 
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CallBackNotifyProc: type « procedure [window: window.Handle, results: Results] 
RETURNS [done: boolean]; 

Call-back notification allows the client to receive all input. It is useful for something like 
mouse tracking when a menu is posted. CallBack uses table to match all user input and 
calls notify for each successful match in the table with window and the results from the 
table as parameters. Call Back will continue to send all notifications to notify as long as 
notify returns done: false. Call-back notification is similar to setting the Manager e.xcept 
that the client's call stack is not unwound. User actions that are not matched are discarded. 

55.2.10 Manager 

Manager: type « record [ 

table: Table, window: window.Handle, notify: NotifyProc]; 

nullManager: Manager « [nil. trash, trash]; 

Manager is used to send all user actions through table and notify, using window instead of 
through the window, table, and notify procedure determined by actionTo Window and TIPs 
Match process. If table is nil, as in nullManager, then the standard mechanisms will be 
used to determine where actions will be sent. 

GetManager: PROC returns [current: Manager]; 

GetManager returns the current manager. 

ClearManager: procedure » inline . . .; 

ClearManager sets the manager to nullManager. It should only be called by clients who 
know that they set the manager from null to non-nuU. 

SetManager: procedure [new: Manager] returns [old: Manager]; 

SetManager does the obvious thing. 

53.2.11 User Abort 

UserAbort: proc [window.Handle] returns [boolean]; 

UserAbort returns whether the user abort flag is set for the window. The bit may be set by 
calling SetUserAbort or by the system if the window does not have an attention procedure 
and the stop key is depressed in that window. If window is nil, the U serin put package 
checks to see whether the user has done a global abort. When a non-shift key goes down, 
this flag and the global abort flag are cleared. 

ResetUserAbort: proc [window.Handle]; 

ResetUserAbort sets user abort flag for the window to false. 

SetUserAbort: proc [window.Handle] 
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SetUserAbort sets the user abort flag for the window. This does not call the window's ^Jii% 
attention procedure, if there is one. 

55^12 Attention 

AttentionProc TYPE = proc [window: window.Handle]; 

An AttentionProc is a procedure called whenever the stop key is depressed. It Is called from 
a high-priority process— not the Notifler— as soon as the stimulus level sees the key go 
down. 

SetAttention: proc [ window.Handle, attention: AttentionProc] 

SetAttention sets the attention procedure for the window. The procedure attention is 
called asynchronously whenever the STOP key is depressed. 

55.2.13 Stuffing Input into a Window 

StuffCharacter: proc [ 

window: window.Handle, char: xstring.Character] returns [boolean] 

StuffCharacter allows a client to drive the type-in mechanism as though a character were 
coming from the user. The notify procedure of window is called with a string result that 
contains char. The returned boolean is true only if window was prepared to accept input. 

Stuff CurrentSelection: proc [window: window.Handle] returns [boolean] 

StuffCurrentSeiection allows a client to drive the type-in mechanism as though the 
contents of the current selection were coming from the user. The selection is converted to a 
string and the string is passed to the window's notify proc. (See the Selection interface for a 
description of the current selection.) The returned boolean is true only if window was 
prepared to accept input. 

StuffResuits: procedure [window: window.Handle, results: Results]; 
Stuff Results calls the notify proc of window with results. 

StuffString: proc [window: window.Handle, string: xstring.Reader] returns [boolean] 

Stuff String allows a client to drive the type- in mechanism as though string were coming 
from the user. The notify procedure of window is called with a string result that contains 
string | . The returned boolean is true only if window was prepared to accept input. 

StuffSTRING: procedure [window: window.Handle, string: long string] 

RETURNS [boolean]; 

StuffSTRING calls the notify procedure of window with a results list that contains a string 
ResultObject whose reader body describes the characters in string. 

StuffTrashBin: proc [window: window.Handle] returns [boolean] ^,^1^1^ 
StuffTrashBin is currently not implemented. 
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55.2.14 Errors 

InvalidTabie: signal [type: TabieErrorr message: xstring.Readerl; 
TabieError: type > {fileNotFound, badSyntax};. 



InvalidTabie is only raised by CreateTabie. The type is f lieNotFound if the file could not be 
found and the message string was empty. fileNotFound is raised as an error . The type is 
badSyntax if the current file is syntactically incorrect. If badSyntax is RESUMEd, and 
message is not empty, the message is written into file, and it is reparsed. If the file has 
been overwritten, or message is empty, and there is a syntax error, the error will be 
badSyntax. In this case if the signal is resumed, CreateTabie simply returns nil. 

Error: error [code: ErrorCodej; 

ErrorCode: type ■ {noSuchPeriodicNotifier, other}; 

ReturnToNotifier: error [string: xstring.Reader]; 

Sometimes a client is deep in the call stack of some Notifler-invoked operation from which 
it wishes to unwind. The error ReturnToNotifier can be raised and will be caught at the top 
level of the Notifier process. Clients can catch this error, post a message with string in it, 
and let the error propagate up: 

55.2.15 Miscellaneous Items 

GetPiace: procedure [window: window.Handle] returns [window.Place]; 



GetPlace returns the window relative coordinate of the last user action that was matched.- 
GetPiace should only be invoked while in the notifier process, 

actionToWindow: packed array KeyName of boolean; 

actionToWindow determines if a user action should be sent to the window containing the 
cursor (TRUE) or to the window containing the current input focus (false). This array is 
global to the entire environment. It is initialized to have all actions go to the input focus, 
except those associated with the Adjust, Menu, and Point mouse buttons and the STOP key. 

caretRate: Process.Ticks: 

clickTimeout: Systam.Pulses; 

clickTlmeout and caretRate are values that are set by user profile. Clients who implement 
blinking carets may use caretRate to determing the rate of caret blinking. Clients who 
implement click timeout without using the timing facilities in tables may use clickTimeout 
to determine the maximum time allowed between two clicks of a multi-click. 

FiushUserlnput: procedure; 

FtushUserlnput empties the queue of pending user actions (type-ahead and button-ahead). 
GetNotiflerProcess: procedure returns [process]; 
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GetNotifierProcess returns the current notifier process. It is defined in TIPXX.mesa. jgm 
timeToFirstRepeat: Process.Miliiseconds; 
timeBetweenRepeats: Process.Milliseconds; 

timeToFirstRepeat and timeBetweenRepeats are for clients who wish to implement 
repeating keys. A key is a repeating key, if while the key is held down continuously, the 
same action is performed each time an interval elapses. The value for the first interval is 
the timeToFirstRepeat. The value for successive intervals is timeBetweenRepeats. 

53.2.16 **Look-Ahead** 

TIP allows a client to "look ahead" at the next results that TIP will deliver, and choose to 
process the results or not. This allows the client to implement possible performance gains. 
For example, say the client's NotifyProc is called with a string result (the user typed some 
characters) and suppose there is some significant "setup" processing the client must do to 
get to the point where the characters can actually be inserted and displayed. If the next 
thing in the input queue is more characters, the client can save that setup processing time 
by looking at what's next in the input queue before returning from the NotifyProc and 
continuing to process characters until the next item in the queue is not a string result. 

GetResuits: procedure [window: window.Handle, resultsWanted: ResultsWanted nil] 
RETURNS [resuits:Resuits]; 

ResuitsWanted: type ■ procedure [ 

window: window.Handle, table: Table results: Results] 
RETURNS [wanted: boolean]; 

GetResuits calls resultsWanted and if resultsWanted returns true, then GetResuits returns 
the results that would next go to window's NotifyProc, and removes from the input queue 
the event that produced results. If resultsWanted returns false, the event is left in the 
input queue and processed "normally." When resultsWanted is called, results is the next 
results and window is the window that those results would go to. If table is not nil, then 
the results would go to the table's NotifyProc. These items are defined in TIPX.mesa. 

55.3 Usage/Examples 

35.3.1 Periodic Notification 

The following example shows the use of a periodic notifier for updating a display of the 
volume page count. The page count will be updated every 20 seconds, provided that the 
Notifier is not otherwise occupied. 

window: window.Handie 

updateCount: Atom.ATOM 4-Atom.MakeAtom[''UpdateCount''L]; 
results: ResultsObject [next: nil, body: atom(a: updateCount]]; 

pageNotif ier: PeriodicNotify ^ ^^Hl^ 
CreatePeriodicNotifty[window: window, results: ©results, milliseconds: 20000]; 

MyNotifyProc: NotifyProc ■ { 
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input: Results; 

FOR input <- results, results.next oo 
WITH z: input select from 
atom ■ > 

IF z.a a updateCount then { 

" code to update page count on screen;} 

ELSE{ 

— coefe to handle other atoms}: 
endcase; 

ENOLOOP}: 



55.3.2 Syntax of TIP tables 



Following is the BNF description for the syntax of tables. Non-terminals are boldface, 
terminals are non-bold Titan (e.g., FastMouse). The characters 
" s >'», •*{'», and in the BNF below are terminal symbols. The semantics are described 
in the next section. 



TIPTable 



Options 

OptionList 

Option 

SmaliOrFast 

FastOrSlowMouse 

Expression 
Statement 

TriggerStmt 
EnableStmt 



:: • Options TriggerStmt . 

Note: tables terminate with a period. 

:: a empty I OPTIONS OptionList; 
:: a Option I Option , OptionList 
:: a SmaliOrFast I FastOrSlowMouse 
:: a Small I Fast 
:: a FastMouse I SlowMouse 

:: a ANDTriggerChoicel WHILE EnableChoicel = > Statement 
:: a TriggerStmt I EnableStmt I Results 

:: a SELECT TRIGGER FROM TriggerChoiceSeries 
:: a SELECT ENABLE FROM EnableChoiceSeries 



TriggerChoiceSeries 



EnableChoiceSeries 



TriggerChoice 
EnableChoice 
FinalChoice 

TriggerTerm 
EnableTerm 

TimeOut 

KeyEnableList 



i TriggerChoice ; TriggerChoiceSeries 
I TriggerChoice ENDCASE FinalChoice 
I ENDCASE FinalChoice 
I EnableChoice ; EnableChoiceSeries 
I EnableChoice ENDCASE FinalChoice 
I ENDCASE FinalChoice 

I TriggerTerm Expression 
I EnableTerm Expression 

■ empty | = > Statement 

. (Key I MOUSE I ENTER I EXIT) Timeout 

■ KeyEnableList | Predicateldent 

■ empty | BEFORE Number | AFTER Number 



:: a Key | Key | KeyEnableList 

Nate: the \ between Key and 

terminal and must be entered. 



KeyEnableList is a 
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Key 
Results 

Resuitltems 
Resultltem 



Keyident Up | Keyldent Down 

Resultltem | Resultltem , Results | Resultltem Expression 
{ Resuitltems } 

Resultltem | Resultltem Resuitltems 

COORDS I BUFFEREDCHAR | CHAR | KEY | TIME 

Number! String { Resultldent 



String 

Resultldent 

Keyldent 

Predicateldent 



"any sequence of characters not containing a 

Ident 
fdent 
Ident 



Mil 



55.3.3 Semantics of Tables 



The whole match process can be viewed as a select statement, that is continuously reading 
key transitions, mouse movements, or key states from the input queue. A trigger 
statement has the eiTect of looking at the next action recorded in the input queue and 
branching to the appropriate choice. An enable statement implies selection between the 
different choices according to the current state of the keyboard or the mouse keys. Trigger 
terms may appear in sequence, separated by and. They might be mixed with enable terms, 
which in turn are characterized by the keyword while. A timeout following a trigger 
indicates a timing condition that has to hold between this trigger and its predecessor. The 
number associated with the timeout expresses a time interval in milliseconds. Events 
starting with the same sequence of trigger and/or enable terms are expressed as nested 
statements. Result items may be identifiers, numbers, strings, or the keywords COORDS, 
BUFFEREDCHAR, CHAR, KEY, or TIME. The results of a successfully parsed event are 
passed to the client. Numbers are passed as LONG integers, and strings as 
xstring.ReaderBodys. BUFFEREDCHAR and CHAR come as xstring.ReaderBodys 
containing the character interpretation of the key involved with the event as defined by 
the CharTransiator. COORDS results in a window. Place containing the mouse coordinates of 
the event. 



Option 
SmallOrFast 



FastOrSiowMouse 

FastMouse 
SlowMouse 



:: ■ SmallOrFast I FastOrSiowMouse 
:: ■ Small | Fast 

TIP can produce its internal table in two formats: one designed 
for compactness (default) and one for speedy execution. This 
option indicates which format should be used. 

:: • FastMouse I SlowMouse 

The TriggerTerm MOUSE means all mouse movement. 

The TriggerTerm MOUSE means only the most recent mouse 

motion (default). 



Expression 

AND TriggerChoice 



:: M AND TriggerChoice I WHILE EnableChoice I = > Statement 

match if and only if TriggerChoice is the next input event after 
the preceding choice. For example, A Down AND B Down 
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means A goes down and then B goes down (with no intervening 
actions like A Up or mouse motion). 

WHILE EnabieChoice match if EnableChoice is also true at this point. For example, A 

Down WHILE B Down matches if A goes down while B is 
doMm. 



3 > Statement 

Statement 
TriggerStmt 
EnableStmt 
EnableStmt 

TriggerStmt 
TriggerTerm 

Key 

MOUSE 

ENTER 

EXIT 

TImeOut 

BEFORE Number 



AFTER Number 



EnableTerm 

KeyEnabieLlst 

Key 

Key 

Keyldent 



continue processing at Statement (it is used for results and 
common prefixes). 

■ TriggerStmt | EnableStmt { Results 

• SELECT TRIGGER FROM TriggerChoiceSeries 

a SELECT ENABLE FROM EnabieChoiceSeries 

matches if any of the EnabieChoiceSeries have already 
happened. 

matches if any of the TriggerChoiceSeries have just happened. 
:: - (Key I MOUSE I ENTER I EXIT) Timeout 

matches if the appropriate key transition occurs. 

matches if there is mouse motion (useful for tracking the mouse). 

matches if the mouse enters the window. 

matches if the mouse leaves the window. 

:: ■ empty I BEFORE Number I AFTER Number 

matches if the associated TriggerTerm l:^ppens within a number 
ofmilliseconds of the preceding (matched) user action. For 
example, A Down AND B Down BEFORE 200 would 
match if A went down and then B went down within 1/5 second 
(and there were no intervening actions). 

matches if the associated TriggerTerm happens a number of 
milliseconds or more after the preceding user action. For 
example, A Down AND B Down AFTER 200 would 
match if A went down and then B went down more than 1/5 
second later (and there were no intervening actions). 

:: ■ KeyEnableList I Predicateldent 

is true if any of the Keys are true. 
: : • Keyldent U P | Keyident DOWN 

is true if the appropriate transition has happened (if this is part 
of a trigger term, is the current user action; if this is an enable 
term, it has already happened). 

identifies the keyboard key. The identifiers should be one of: A ... 
Z, One, Two, Three, ... Zero, Adjust, AGAIN, OpenQuote, 
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DEFAULTS, BackSlash, BS, SUBSCRIPT, SMALLER, Comma, 
KEYBOARD, TAB, PROPS, COPY, Minus, DELETE, 
MARGINS, Equal, EXPAND. FIND, HELP, ITALICS, 
UNDERLINE, Keysetl. Keyset2, Keysets, Keyset4, Keysets, 
LeftBracket, LefbShift, LOCK, MouseMiddle, CENTER, MOVE, 
NEXT, SAME, Period, Point, CloseQuote, SUPERSCRIPT, 
RETURN, RightBracket, RightShift, BOLD, SemiColon, Slash, 
Space, OPEN, PARATAB, UNDO. STOP, A8, A9, AlO, All, 
A12, LI, L4, L7. LIO, Key47. R3, R4, R9, RIO 

Note: There are no names for shifted characters like left or right 
paren. Instead, specify one or both shift keys plus the unshifted 
key name. For example. Nine Down WHILE LeftShift Down 
instead of LeftParen Down. 



Resuititem 

String 
Resuitldent 

COORDS 

BUFFEREDCHAR 



CHAR 
KEY 



TIME 

String 

Number 

Resuitldent 



See LevellVKeys and the Pilot Programmer's Manual for 
(610E00160) more information on the keyboard. 

:: - COORDS I BUFFEREDCHAR I CHAR I KEY] TIME 

I String | Number | Resuitldent 
:: ■ "any sequence of characters not containing a "" 
:: ■ Ident 

return a coord ResultEiement with the coords of the last user 
action. 

return a string ResultEiement containing the character 
representations of the last user actions that were also buffered 
characters. 

sameasBUFFEREDCHAR 

return a key ResultEiement with the current state of the key (not 
recommended In normal usage. Usually a more complex TIP 
table is indicated if you are using this result), 
return a time ResultEiement with the time of the last (matched) 
user action. 

return a string ResultEiement. 
return an integer ResultEiement. 
return an atom ResultEiement. 



Predicateldent 
Predicateldent 



Ident 



a predicate is an atom which can have a procedure associated 
with it (defined in SpecialTIPX.mesa). This procedure returns a 
BOOLEAN and it is called by TIP when a predicate atom is 
encountered in a TIP table. Several useful predicates are 
provided by ViewPoint, to distinguish physical keyboards: 
"aLevel4'*, "eLeveU", "jLeveU", "aLevelS", "eLevelS", "jLevelS" 
(where a = American, e = European, j = Japanese, Level 4 = 
8610, Levels = 6085). For example, adding this to a TIP table: 
TAB Down = > SELECT ENABLE FROM 

eLevelV s > SomethingSpecial 

ENDCASE; 

would result in ''SomethingSpecial** being passed in the results 
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list if and only if the TAB key went down on a European 6085 
keyboard. See NormalKeyboard.TIP in Appendix A for more 
examples. 



35.3.4 Example Table 



SELECT TRIGGER FROM 
Point Down = > 

SELECT TRIGGER FROM 

Point Up BEFORE 200 AND Point Down BEFORE 200 = > 
SELEa ENABLE FROM 

LeftShift Down = > COORDS, ShiftedDoubleClick 
ENDCASE s > COORDS, NdrmaiDoubleClick; 
Adjust Down BEFORE 300 = > PointAndAdjust; 
ENDCASE = > COORDS, SimpleClick; 



This table produces the result element (atom) Normal Doubled ick along with the 
mouse coordinates if the left mouse button goes down, remains there not longer than 200 
ms, and goes down again before another 200-ms elapse. The result is 
ShiftedDoubleClick if the same actions occur but also the left shift key is down. If 
the right mouse button also goes down less than 300 ms after the initial Point Down 
and the left mouse button also goes down, PointAndAdjust results. Finally, the table 
specifies the result SimpieClick (with coordinates) if Point goes down but none of the 
above-described succeeding actions occurs. 

35.3.5 Simple TIP Client Example 

This example shows a simple TIP client. The window acts in the following manner. If the 
left (Point) mouse button is depressed the window becomes the input focus and the 
cursor changes to its special shape. As long as the window is the input focus and the 
cursor is in the window, it remains the special shape but returns to the original shape 
when the mouse leaves the window. The place in the window where the depressed left 
(Point) mouse button is released is the place where text is displayed. 

The procedure InitAtoms is part of the initialization code and creates the four atoms that 
the notify procedure understands. It is put in a separate procedure so the string literals 
will not be allocated in the global frame. The procedure InitWindow initializes the 
window by attaching the context data and setting the table and notify procedure. 

This example uses the system's table from TIPStar. The fragments of the 
NormalMouse.tip portion of TIPStar's normal table that are used to generate the atom 
results in this example are 

Point Down = > SELECT ENABLE FROM 

[SHIFT] = > TIME, COORDS, Shift, PointDown; 
ENDCASE = > TIME, COORDS, PointDown; 



Point Up = > SELECT ENABLE FROM 

[SHIFT] a > TIME. COORDS, Shift. PointUp; 
ENDCASE = > TIME. COORDS, PointUp; 

ENTER = > Enter; 
EXIT = > Exit; 
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The notify procedure TIPMe looks at the results and understands four atoms and string _ 
input. For the atom pointDown, if the window is not already the input focus, it sets the 
window as the input focus and sets the cursor to its special shape. For the atom pointUp, 
it saves the place the event occurred as the location to display text. The enter atom just 
fiddles with the cursor if the window is the input focus. The exit atom restores the 
cursor. If the window is the input focus and the user types into the window, a string 
result is sent to the notify procedure containing the characters typed. The 
NormalKeyboard.tip portion of TIPStar's normal table contains the buffereochar results 
for the keyboard-keys-going dovm events. 

Handle: TYPE « lon<3 pointer to Object; 
Object: type » 

contextType: Context.Type « Context.UniqueType(]; 
pointOown, pointUp, enter, exit: Atom.ATOM; 

InitAtoms: procedure » { 

pointOown *- Atom.MakeAtonn["PointOown"L]; 
pointUp 4- Atom.MakeAtom(''PointUp"L]; 
enter <- Atom.MakeAtom("Enter"L]; 
exit 4- Atom.MakeAtom(''Exit"L]}; 

InitWindow: procedure [window: window.Handle] ■ { 
h: Handle » zone.NEw(Object«-(]l; 

Context.Create{type: contextType, data: h, proc: OestroyContext, window: window]; 
TiP.SetTabieAndNotifyProc{ 

window: window, table: TiPStar.NormalTabieQ, notify: TIPMe]}; 0^ 

TIPMe: Tip.NotifyProc ■ { 

h: Handle * Context.Find[type: contextType, window: window]; 
place: window.Place; 

FOR input: TiP.Resuits *- results, input.next until input » nil oo 
WITH z: input select from 
coords a > place *- z.place; 
atom a > select z.a from 
pointOown ■ > 

IF '-h.haslnputFocus then ( 
TiP.SetlnputFocus{ 

window: window, takeslnput: true, 
newlnputFocus: MyLosingFocusProc, cllentData: h]; 
SaveCursorAndSetMlne[h]} 
pointUp ■ >' h.textPlace ^ place; 

enter ■ > if h.hasinputFocusTHENSaveCur$orAndSetMine[h]; 
exit M > RestoreCursor(h]; 
enocase; 
string a > 

h.textPlace DisplayTextAtPlace[h: h, reader: (§}z.rb, place: h.textPlace]; 
enocase; 
enoloop}; 

MyLosingFocusProc: Tip.LosingFocusProc a { 
OPEN h: NARROw(ciientData, Handle]; 
h.hasinputFocus <- false}; 
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55.3.6 Modifying an Existing TIP Client 

This example shows how an existing TIP client may be modified. Assuming the existence 
of a Text Window package similiar to that in Tajo, this example builds a TTY-like 
window on top of it. It modifies the text window's behavior in two ways. First, it changes 
the table that the text window uses by linking its own table on the front of the normal 
table that the text window package uses. It also has its own notify procedure that just 
looks for the STOP key going down but passes all other notifications to the text window's 
notify procedure that it saves. 

This example writes its own table. The table maps shift backspace to the character 
Control-W, backspace to the character Control-H, the DELETE key to the DEL character 
and the tab key to the ESCAPE character. This table handles only a few of the functions 
and is linked onto TIPStar's normal table to provide the bulk of the funtion. 

- File: TTY.tip 

[DEF SHIFT. (LeftShift Down | RightShift Down | Key47 Down | A12 Down)] 

SELECT TRIGGER FROM 

BS Down = > SELECT ENABLE FROM 
[SHIFT] = > •\027"; 
ENDCASE = > '•\010*; 

DELETE Down = > "M??"; 

TAB Down = > "VOaS*; 

ENDCASE. 

Handlej type ■ long pointer to Object; 
Object: type » . . .; 

contextType: Context.Type a context.UniqueTypeQ; 
stop: Atom.ATOM; 

Init: PROCEDURE ■ { 

rb: XString-ReaderBody ♦-XStrlng.PromSTRINGl''TTY.tip"L]; 
stop4- Atom.MakeAtom(''Stop''L]; 
myTabie 4-TIP.CreateTable{file: @rb]; 

Q ^TIP.SetTableLink(froni: mylabie, to: TIPStar.NormalTabieQ}; 

Create: procedure [window: window.Handle, ...]■{ 
h: Handle ■ zone.NEw{Object <- []]; 
TextWindow.Create(window, . . .]; 

h.oldNotify «-TiP.SetNotifyProc(wlndow: window, notify: TlPMe]}; 

TIPMe: Tip.NotifyProc ■ { 

h: Handle ■ Context.Find[type: contextType, window: window]; 
WITH z: results select from 

atom a > SELECT Z.a FROM 

stop « > { 

TiP.FlushUserlnput(]; 
SendHaltNotif ication[h] ; 

RETURN}; 
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enocase; 

h.oidNotify [window, results]}; - normally pass results to text window's notify 



55.3.7 Macro Package 

The macro package used in TIP is based on the general-purpose macrogenerator 
described by Strachey in Computer Journal (October 1965). The following summary is 
based on that article; see the article itself for more details. 

A macro call consists of a macro name and a list of actual parameters, each separated by 
a comma. The name is preceded by a left square bracket ([), and the last parameter is 
followed by a right square bracket. A macro is defined by the special macro DEF, which 
takes two arguments: the name of the macro to be defined and the defining string. The 
defining string may contain the special symbols ^1, -~2, etc., which stand for the first, 
second, etc., formal parameters. Enclosing any string in parentheses prevents 
evaluation of any macro calls inside; in place of evaluation, one layer of string quotes is 
removed. It is usual to enclose the defining string of a macro definition in string quotes 
to prevent any macro calls or uses of formal parameters from being effective during the 
process of definition. 

Here are some sample macros and an example: 

- macro definitions 
[DEF,LSHIFT,(LeftShift Down)] 
[DEF.RSHIFt.(RightShift Down)] 
[DEF,EitherShift,( 

[LSHIFT] = > -1; 

[RSHIFT] =>-!)] 

~ trigger cases 

SELECT TRIGGER FROM 

BS Down = > SELECT ENABLE FROM 

[EitherShift,{BackWord}l; 

ENDCASE 3 > {Backspace}; 
-more cases... 
ENDCASE... 

The above example expands to: 

BS Down 3 > SELECT ENABLE FROM 
LeftShlft Down = > Back Word; 
RightShift Down a > BackWord; 
ENDCASE a > {Backspace}; 
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55.4 Index of Interface Items 



Item 


Page 


Item 


Page 


actionToWindow: array of boolean 


11 


LosingFocusProc: type 


7 


ATOM: TYPE 


4 


Manager: type 


9 


AttentionProc: type 


10 


NotifyProc: type 


4 


backStoplnputFocus: window.Handle 


7 


nuilManager: Manager 


9 


CallBack: procedure 


8 


nuilPeriodicNotify: PeriodicNotify 


8 


CailBackNotifyProc: type 


9 


PeriodkNotify: type 


8 


CancelPertodicNotify: procedure 


8 


ResetUserAbort: procedure 


9 


caretRate: Pro<ess.Ticks 


11 


ResultObject: type 


4 


CharTransiator: type 


7 


Results: type 


4 


ClearlnputFocusOnMatch: procedure 


7 


Results Wanted: type 


12 


ClearManager: procedure 


9 


ReturnToNotifier: error 


11 


dickTimeout: System.Puises 


11 


SetAttention: procedure 


10 


CreateCharTabie: procedure 


6 


SetBackStoplnputFocus: procedure 


7 


CreatePeriodicNotify: procedure 


8 


SetCharTransiator: procedure 


3 


CreatePlaceHoiderTabie: procedure 


6 


SetlnputFocus: procedure 


7 


CreateTabie: procedure 


6 


SetManager: procedure 


9 


Destroy Table: procedure. 


6 


SetNotifyProc: procedure 


5 


OownUp: type 


4 


SetNotifyProcForTable: procedure 


6 


Error: error 


11 


SetTabie: procedure 


5 


ErrorCode: type 


11 


SetTabieAnd NotifyProc: procedure 


5 


FfushUserinput: procedure 


11 


SetTableLink: procedure 


5 


FocusTakesinput: procedure 


7 


SetTableOpacity: procedure 


5 


GetCharTransiator: procedure 


8 


SetUserAbort: procedure 


9 


Getin put Focus: procedure 


7 


StuffCharacter: procedure 


10 


GetManager: procedure 


9 


StuffCurrentSeiection: procedure 


10 


GetNotifierProcess: procedure 


11 


StuffResults: procedure 


10 


GetNotifyProc: procedure 


5 


StuffSTRING: procedure 


10 


GetNotifyProcFromTable: procedure 


6 


StuffString: procedure 


10 


GetPlace: procedure 


11 


StuffTrashBin: procedure 


10 


GetResuits: procedure 


12 


Table: type 


5 


GetTabie: procedure 


5 


TableError: type 


11 


GetTabieLink: procedure 


5 


TabieObject: type 


5 


GetTabieOpacity: procedure 


5 


timeBetweenRepeats: 




InvalidTable: signal 


11 


Process.Mil 1 i seconds 


12 


Key Bits: type 


8 


tImeToFirstRepeat: Process.Milliseconds 


12 


KeyName: type 


4 


UserAbort: procedure 


9 


KeyToCharProc: type 


7 


WaitSeconds: procedure 


11 
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56.1 Overview 

The TIP facility provides a mechanism that links a list of TiP.Tabies. These TiP.Tabies contain 
productions that translate user actions into terms a client is prepared to deal with. TIPStar 
creates a structure for the list of ViewPoint TIP tables to be built on. This structure divides 
all possible input actions into logical groups (mouse actions, special keys like UNDO and 
STOP, utility keys like MOVE and COPY, etc.) and provides a means for accessing these 
groups of tables. 

56.2 Interface Items 

36.2.1 The TIPStar Structure 

The basis for the TIPStar structure is the placeholder. 

Placeholder: type ■ {mouseActions, keyOverrides, softKeys, keyboardSpecific, 
blackKeys, sideKeys, backstopSpedalFocus}; 

A placeholder table is created for each of the enumerateds in Placeholder. Placeholder 
tables are empty TIP tables linked to form a list. This list divides all possible input actions 
into logical groupings as discussed in the Overview above. It defines a series of segments 
for the list of TiP.Tabies to be built upon. Segments (mini-stacks) are delineated by the 
placeholder tables. This initial list of TiP.Tabies then, contains only empty tables. Note: 
Placeholder tables are always empty. They are, as their name implies, placeholders-each 
providing a position in the list of babies for adding or removing real tables of a particular 
kind (those relating to mouse actions, those mentioning the soft keys,and so forth.). See 
Examples in the next section. 

Fine point: A set of normal tables that contain all the basic key productions is installed at boot time. See the 
System TIP Tables Appendix for listings of those tables and a view of the TIP table list at the completion of 
booting. These normal tables are referred to as generic in the description of npsur.GetTabie to prevent confusion 
with the procedure TiKtar.NormalTable. 



56-1 



56 TIPStar 



The list of ViewPoint placeholder tables is initialized as in Figure 56.1 (the arrows 
represent the links of the list) . 



Placeholders 



mouseActions 



keyOverrides 



softKeys 



keyboardSpecific 



biackKeys 



backstopSpecial Focus 



NIL 



Input & Uses 



Point and adjust menu 



[e.g,. PROPS when a property sheet is up] 



Interprets top row of keys 



Keys on physically different keyboards 



The physical keyboard and its modifications. 



All those not directed to the input focus. 



Handles STOP, KEYBOARD, UNDO, and friends. 



Figure 56. 1 ViewPoint Placeholder Tables 



56.2.2 Installing and Removing Tables 

A client may alter the table arrangement by pushing or storing a TIP table into any point 
on the tree, or by popping back to a previous table. 



PushTable: procedure [Placeholder, TlP.Table] ; 

PushTable leaves old tables in the watershed, but places the new table (or chain of tables) 
directly after the specified placeholder. This places the new table in front of any others 
within that segment. Thus if the new table mentions the same key actions as the old table, 
the old one is effectively Ignored until the new one is popped. If the new table only 
mentions a few key actions, however, previously pushed tables will be used for the others. 

For an example of PushTable and the resulting tip. Table list, see §56.3.1. 

PopTable: procedure [Placeholder, TiP.Tabie] ; 

PopTable takes the single TIP table to be popped. It is not required that the table to be 
popped be at the top of the placeholder's list. A strict stack discipline is relaxed. 
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StoreTabie: procedure [Placeholder, np.Table] returns [np.Table] ; 

StoreTable replaces the table (or chain of tables) with the client's table (or chain of tables) 
and returns the previous table. The client can restore the old value later, if it wishes. (In 
using StoreTable, and especially in remembering or restoring the old value, the client 
probably needs to be cognizant of the other clients that may manipulate the same 
placeholder.) (See examples in §56.3.3.) 

56.2.3 Retrieving Pointers to Installed Tables 

NormalTabie: procedure returns [tip. Table]; 

NormalTable returns the table at the head of the list (mouseActions placeholder). This is 
the appropriate table to use for a normal TiP.SetTabieAndNotifyProc. 

GetTable: procedure [Placeholder] returns [Tip.Table]; 

GetTable returns the generic table at the specified placeholder, if one exists. (See the fine 
point in §56.2.1.) 

5d.2.4 Mouse Modes 

Mode: type ■ {normal, copy, move, sameAs}; 

The TtPStar.Modes refer to the various modes attributable to mouse actions. These modes 
can be programmatically checked and changed by using the GetMode and SetMode 
procedures outlined below. 

GetMode: procedure returns [mode: Mode]; 

GetMode returns the current mode. 

SetMode:PROCEOURE [mode: Mode] returns [old: Mode]; 

Calling SetMode causes the appropriate TiP.Table to be stored in the TiPStar chain. 

For example, when the COPY key goes down, the call to TiPStar.SetMode[copy] causes 
NormalMouM.TIP to be relaced by CopyModeMous«.TIP. Clients receiving mouse notifications 
receive CopyModeOown instead of PointOown. If the world is in move mode (causing 
Mov«ModeMouse.TIP to be Stored) the client receives the MoveModeOown when mouse point 
is pressed. See the TIP Table appendix for information on the other productions in the four 
mouse tables (NormalMous«.TIP, CopyMod«Mous«.TlP, Mov«Mod«Mouse.TIP and 
SameAsModeMouse. Tl P) . 
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56.3 Usage/Examples 



56.3.1 When PushTable Is Called 



InitiaiizeMyTIPTables: procedure « 

BEGIN 

rbOientAMouse: xstring.ReaderBody 4-xstrtn9.FromSTRING(''ClientAMouse.TiP''L]; 
tipClientAMouse: np.Table 4-Tip.CreateTable(file: ®rbClientAMousei; 
— instail my tip table (tie it to my notify proc) 

a4-Tip.SetNotifyProcForTabie( tipClientAMouse. ClientAMouseNotifyProc]; 
PushTabietmouseActions, tipCiientAMousei; 

rbClientAKeys: xstrmg.ReaderBady <-xstring.FromSTRING("ClientAKeys.TiP''L]: 
ttpOientAKeys: np.Tabie 4-Tip.CreateTable(fiie: SrbClientAKeysi: 
" install my tip table ( tie It to my notify proc) 

a4-Ttp.SetNotifyProcForTable{ tipOientAKeys, ClIentAKeysNotifyProc]; 

PushTable(sideKeys,tipC!ientAKeys]; 

END: " InitiaiizeMyTIPTables 

Assume initially that the list appears as in Figure 56.1. If Client A then pushes two tables 
onto that list, as in the code above, the new links result in the list shown in Figure 56.2.. 



mouseActions 



keyOverrides 



^ ClientAMouse.TIP 



1 



softKeys 



keyboardSpecific 



biackKeys 



sideKeys 



> ClientAKeys.TIP 



backstopSpeci al Focus 



1 



NIL 



Figure 56.2 When PushTable Is Called 
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If client B then pushes another table to the mouseActions placeholder 

PushTabi e(mouseAction$. ti pCl i entBMouse]: 
the resulting list appears as in Figure 56.3. 



softKeys 



keyboardSpecific 



biackKeys 



sideKeys 



mouseActions 


► 


ClientBMouse.TIP 






i 


keyOverrides 


i 


ClientAMouse.TIP 



backstopSpeci ai Focus 



1 



NIL 



ClientAKeys.TIP 



Figure 56.3 Pushing Another Table 



56.3.2 When StoreTable Is Called 

rbCllentCMouse: xstring.ReaderBody xstring.FromSTRING{"ClientCMouse.TiP''L]: 
tipClientCMouse: TiP.Tabie 4-Tip.CreateTabie(fiIe: ^rbCllentCMousei; 
- install my tip table (tie it to my notify proc) 

Q4-TiP.SetNotlfyProcForTabie( tipClientCMouse. ClIentCMouseNotifyProc]; 
savedTabie 4-StoreTabie(mouseActions. tipClientCMousel; 

Assume initially that the list appears as in Figure 56.3. If client C then calls StoreTable 
with another table directed at the mouseActions placeholder, the resulting list appears as 
in Figure 56.4. 
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mouseActions 



keyOverrides 



softKeys 



keyboardSpecific 



biackKeys 



sideKeys 



backstopSpecial Focus 



NIL 



> ClIentCMouse.TlP 



ClientAKeys.TIP 



Figure 56.4 Pushing Another Table 

Client C now has the handle to the segment removed from mouseActions when the 
StoreTabie was done (savedTable, see Figure 56.5). This table (or in this case, chain of 
tables) should be replaced when the client is through with its own mouse tip 
(tipClientCMouse) by a call to: 

StoreTabie[mouseActions, savedTable]; or 
PopTabieCmouseActlons. tipClientCMouse]: 
PushTable(mouseActions, savedTable]; 







ClientBMouse.TIP 










ClientAMouse.TIP 







Figure 56.5 Saved Table 
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36.3.3 When PopTable Is Called 

Assume initially that the list appears as in Figure 56.3. If client A then pops its table at 
the mouseActions placeholder, the resulting list appears as in Figure 56.6. Note: It is not 
necessary for the table being popped to be at the top of the stack (where the top of a stack is 
here defined to be the position immediately following any placeholder table— thus there are 
several stacks within the watershed list of tables). 



mouseActions 



^ ClientBMouse.TIP 



keyOverrides 



softKeys 



keyboardSpecific 



biackKeys 



1 



sideKeys 



> aientAKeys.TIP 



backstopSpecial Focus 



NIL 



Figure 56.6 Pop Table 
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56,4 Index of Interface Items 



Ttnm 




Cmottmntitt' QBO<*vniiaB 


3 


GetTabie: procedure 


3 


NormaiTabte: procedure 


3 


Mode: TYPE 


3 


Placeholder: type 


1 


PopTabie: procedure 


2 


PushTable: procedure 


2 


SetMode: procedure 


3 


StoreTable: procedure 


3 
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57.1 Overview 

The Undo interface provides a set of procedures that allow applications to add Undo 
opportunities to the current Undo stack. An implementation of Undo can then call 
applications when the UNDO key is depressed. 

57.2 Interface Items 

57.2.1 Application's Procedures 
Opportunity: Undo.Proc; 

PrOC: TYPE a PROCEDURE [ 

undoProc: procedure [long pointer], 
destroyProc: procedure [long pointer], 
data: long pointer, 
size: cardinal 0 ]; 

The Opportunity procedure is called by an application when it does something that can be 
undone. The client's undoProc is called to perform an undo. The destroyProc is called when 
the undo opportunity no longer exists. The client can destroy any data at that time. The 
undoProc or the destroyProc will always be called. The client's context for the undoing is 
passed in via the data item: a non-zero size indicates that the Undo implementation should 
copy the words from data f through (data * size-1) | into its zone. If size = 0, the caller's 
long pointer is simply remembered. 

Roadblock: procedure [xstring.Reader]; 

The Roadblock procedure is called by an application when it does something that cannot be 
undone. The immutable string passed in is a message that the Undo implementation can 
issue if the user attempts to undo past this point. The string is copied. 

OoAnUndo: procedure; 
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The OoAnUndo procedure is called when an undo action should be forced. This is typically 
when the keyboard modules notice that UNDO has been pressed. 

OoAnUnundo: procedure; 

The OoAnUnundo procedure is called when an un-undo action should be forced. This is 
typically when the keyboard modules notice that shifb-UNDO has been pressed. 

OeleteAli: procedure; 

The OeleteAli procedure is called to tell the Undo implementation to empty its stack of 
opportunities. This procedure is typically called upon logoff. 



57.2.2 Implementation's Procedures 

Setimpiementation: procedure ( 

undo.Impiementatlon] returns [Implementation]; 

Getlmpiementation: procedure returns [Implementation]; 

implementation: type « record [ 
opportunity: undo.Proc, 
roadblock: procedure [xstring.Reader]« 
doAnUndo: procedure, 
doAnUnundo: procedure. 
deieteAll: PROCEDURE ]; 

These procedures allow an implementation to plug itself in to the Undo mechanism. An 
implementation can supply its set of procedures and can ascertain the current procedures. 
Setimpiementation returns the procedures of the previous implementation. 

An initial set of dummy procedures are provided. They are basically no-ops; the dummy 
Opportunity procedure immediately calls the application's opportunity.destroyProc. 

Zone: procedure returns [uncounted zone] 

Returns the implementation's zone. 

57.3 Usage/Examples 

The application calls Opportunity with some context. The Undo implementation 
eventually calls the application either at its undoProc or its destroyProc. The former is 
called upon a real undo request. The latter is called when the opportunity is about to be 
forgotten: it allows the application to garbage-collect context. The destroyProc is typically 
called to prime the undo stack of very old elements or to prune opportunities that are 
trapped behind a roadblock. 

At the application's undoProc or destroyProc, the argument is either (1) the original 
pointer passed in to Opportunity, if size was zero or (2) a pointer into the Undo 
implementation's zone that points to a copy of the application's data. In the latter case, the 
data is freed by the Undo implementation right after the call. Exception: if the help 
implementation is a no-op implementation, it can call the application's destroyProc from 
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inside the Opportunity call. In this case, the help implementation can present the original 
pointer to the destroyProc even if size is non-zero. 

37^.1 Example 

MyUndoOataObject: type * record [...]; 

MyUndoOata: type » long pointer to MyUndoOataObject; 

complaint: xstring.ReaderBody <-xstrmg.FromSTRING ["Can't do that^L]; 

UndoProc: procedure [myUndoOata: MyUndoOata] * { 

— does something appropriate, like a partial cleanup of data structures.message 
" might post a about current state for the user. 
undcZone [l-FREE [@myUndoOata]; 

}; 

DestroyProc: procedure [myUndoOata: MyUndoOata] a { 
UndcZone [].FREE [@myUndoOata]; 

}; 

— Mainline code 

~ Code that cannot be undone 

Undo. Road block [©complaint]; 

— Code that can be undone 

Undo.Zonen.NEw[MyUndoOataObject [...] ]; 

undo.Opportunity [undoProc: UndoProc, destroyProc: OestroyProc, data: myOata]; 
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57.4 Index of Interface Items ^i*!*, 



Item 


Page 


OeieteAil: procedure 


2 


OoAnUndo: procedure 


1 


DoAnllnundo: procedure 


2 


Getlmplementation: procedure 


2 


Implementation: type 


2 


Opportunity: procedure 


1 


Proe: type 


1 


Roadblock: procedure 


1 


Set! mpiementation : procedure 


2 


Zone: procedure 


2 
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58.1 Overview 

UnitConversion provides for converting numbers between various units of measure. 

58.2 Interface Items 

Units: type » {inch, mm, cm, mica, point, pixel, pica, didotPoint, cicero}; 

Units defines all the units that may be converted, point is printer point, pixel is screen dot. 
pica = 12 points. 

ConvertReal: procedure [n: XLReaLNumlser, inputUnits, outputUnits: Units] 
RETURNS (xLReai.Number]; 

ConvertReal converts n from InputUnits to outputUnits, using XLReal. May raise 
xutoaLError. 

Convertlnteger: pRoaouRE [n: long integer, inputUnits, outputUnits: Units] 

RETURNS [long INTEGER]; 

Convertlnteger converts n from inputUnits to outputUnits. May raise XLR«ai.Error. 

58.3 Usage/Examples 

5S.3.1 Converting Font Values 

The following example implements a real-number conversion utility: 

Unit: TYPE ■ MACHINE DEPENDENT {inch(0), mm(1), mica(2), point(3), space(4), cm(5), (1 5)}; 

Convert: PUBUCPR0C[n: XLReai.Number, inputUnits, outputUnits: Unit.Units] 
RETURNS [xLReai.Number] a { 
IP inputUnits ■ outputUnits then return [n]; 
IF inputUnits ■ space then 

RETURN 

UnitConv«rsion.ConvertReal( 
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XLRaai.Multiply[n, pointPerSpaceLseventySecondOfAnlnchr 
ConvertUnitstoutputUnits]]; 

IFOUtputUnitS a space THEN 
RETURN 

xutMl.Oivide(unitConv«rsion.ConvertReai(n,ConvertUnits(inputUnitsL 
seventy SecondOfAnlnchLpointPerSpace]; 

RETURN 

UnitConv«rsion.ConvertReal t 

n, ConvertUnitsCinputUnits], Con vertUnitsfoutputU nits]]}; 

ConvertUnits: proc [u: Units] returns [unitConv«rsion.Units] ■ { 
IP u < mica then return [vai.[u.ORO]]; 
iFu ■ mica THEN RETURN [val[u.0RD + 1]]; 

IFU a point THEN RETURN [VALIu.ORD + 611; 
RETURN [cm] 

}; 
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58 A Index of Interface Items 

Item Page 

Convertlnteger: procedure 1 

ConvertReai: PRoaouRE 1 

Units: type 1 
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59.1 Overview 

The Window interface supplies facilities for managing windows on the display screen. A 
window is a rectangular region of the display screen in which a client can display 
information to the user. A window may overlap another window or even completely cover 
it. A window may extend past the edges of the physical display screen or even be 
completely outside it and thus not visible. Windows may be moved around horizontally and 
vertically, have their size changed, and have their depth changed in the stack of windows 
visible on the screen. Window shields the client from these considerations-from the 
client's point of view, each window is unaffected by other windows or by the edges of the 
display screen. Window automatically handles client requests to paint into window 
regions that are not currently visible on the screen. 

The Display interface supplies routines for painting into windows. 



39.1.1 Window Creation 

Window supplies operations to allocate and free a window (a window.Object). However, 
windows are usually not allocated directly by clients but are obtained from various other 
facilities, such as StarWindowSheli or Form Window. Once allocated, a window is referred 
to and manipulated by reference, using a window.Handie. 

59.1.2 CMd Windows and the Window Tree 

Window manipulates a tree of windows. A window may have child windows. Child 
windows obscure their parent; that is, they are above their parent in the apparent stack of 
windows visible on the screen. A child window may be entirely contained within its 
^eurent's screen area, may project beyond its parent's edges, or may even be completely 
outside its parent. Window automatically clips the display of a child window at its parent's 
edges. Thus a child window that is completely outside its parent is not visible on the screen 
at all. 

Each window has an ordered list or stack of its child windows. Sibling windows may 
overlap: if they do, one that appears earlier in the stack is on top of or obscures one that 
appears later. The first window in the stack is the top sibling, and the last is the bottom 
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sibling. Each window has a pointer to its parent, a pointer to the next sibling of its parent, 
and a pointer to the window's topmost child. 

When a window is created, it is not in the window tree and is called a private window. A 
private window is unknown to Window and is not displayed on the screen. Window 
provides facilities for inserting private windows into the tree, moving them within the tree, 
and removing them from it. A window that is in the tree will be wholly or partially visible 
on the screen unless it is entirely outside its parent's area or unless its children completely 
cover the portion that is within its parent. Private windows may also be built into private 
trees J which can be inserted into and removed from the window tree as a unit. 

Display supplies the root window, which is the root of the window tree and corresponds to 
the entire display screen. The root window typically supplies the background pattern. 

Each window has its own coordinate system: the upper-left corner is the origin [x: 0, y: 0], 
with X increasing to the right and y increasing downward. A window's location is defined in 
terms of its parent's window coordinate system. Coordinates may be positive or negative, 
and thus a window can have any location relative to its parent. 

39.1.3 Painting into a Window 

Every window contains a client-supplied display procedure that will, on demand, paint all 
or part of the window. Note that windows can be much larger than the display screen; any 
paint directed to non- visible portions of a window (or outside the window entirely) is 
discarded. Thus, a client never needs to be concerned about what parts of its window are 
covered by other windows or what parts are off the screen. As a convenience to clients, 
requests to paint into a window that is not currently in the window tree are also ignored. 

The Display and SimpleTextDisplay interfaces provide a variety of procedures for painting 
various things into a window, including character strings, black, white, or gray boxes, and 
various graphics, such as curves and lines. 

The display background color, which is represented by a pixel value of zero, is commonly 
called white and a value of one is called black. Note: The display hardware also can render 
the picture using zero for black and one for white. Clearing or erasing an area of the screen 
means setting all of its pixels to zero, or white. 

A display procedure usually wants to start with an erased (zero) area and logically OR the 
black pixels into the area. Window supplies an accelerator clearingRequired to minimize 
unnecessary erasures. If clearingRequired a true. Window guarantees that when the 
display procedure is called to paint the window, all of the window's pixels that should be 
white indeed are white. In that situation, the window might contain any combination of its 
previous contents and erased areas. On the other hand, some display procedures want to 
set all pixel values, completely overwriting the previous contents. These windows should 
specify clearingRequired « false. 

Areas displayed on the screen may become incorrect or invalid for many reasons, such as 
when a window that was visible is deleted. A client can also mark an area invalid. Window 
accumulates these invalid areas and then, in response to a client call to Validate or 
ValidateTree, calls the various windows' display procedures to paint the necessary areas. 
Validate and ValidateTree are the only Window operations that cause immediate screen 
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painting. All other operations merely enqueue work to be performed by a later Validate 
operation. Fine point: The few special cases that do not follow this rule are noted in the text. 

The standard way for a client to paint into its window is to update its data structures, 
invalidate the portion of its window that needs to be painted, and then call a Validate 
routine. Window responds by calling back into the client's display procedure to do the 
painting. 

When a window's display procedure is called, it has access to a list of the invalid areas of 
the window (see EnumeratelnvalidBoxes). It may choose to paint the entire window or, 
alternatively, to enumerate the invalid areas and just paint those areas. In any case, 
Window clips all the display routine's paint requests to the boundaries of the invalid 
areas-paint directed to other areas is discarded. In special circumstances, the client may 
wish to paint into valid visible areas. The operation FreeBadPhosphorList deletes the 
display routine's invalid area list; for the lifetime of that invocation of that display 
procedure, paint requests are clipped only to the boundaries of the visible parts of the 
window. 

If display routines are called from outside the invocation of a window's display procedure, 
the paint requests will be clipped to the boundaries of the visible parts of the window. 

59.1.4 Bitmap-under 

The window package allows clients to associate a window with a bitmap-under. This is a 
block of memory that is used to hold the pixels that are covered up by the window. It allows 
Window to move or delete such a window quickly, since it can repaint the display directly 
by using the contents of the bitmap-under instead of calling client display procedures. A 
bitmap-under is commonly used for menu windows. This is discussed in greater detail 
under §59.2.7. 



59.1.5 Window Panes 

The window package normally maintains a detailed list of invalid regions and allows 
arbitrary overlapping of windows without requiring the client to worry about other 
windows. Some clients would prefer to have greater control over their windows at the 
expense of more restrictions over their use. Window panes are such a mechanism. If a 
window is a window pane, the client must ensure that it does not overlap any of its siblings 
and that the parent does not paint underneath the pane. A further restriction is that only 
window panes may be children of panes. In return, the window package can do much less 
calculation to determine invalid regions. The window package does not enforce these 
restrictions. It is up to the client to follow them, or the screen appearance maybe 
Inconsistent. The client must specify whether a window is a window pane when it is 
initialized. 

59.1.6 Linked Windows 

The window package allows multiple windows to linked together to make it easy for client 
software to support displaying the same data into multiple windows. Linked Windows are 
designed so that whatever data is painted into one window will be painted into all of the 
other windows. This is discussed in greater detail under §59.2.8. 
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59.1.7 Buffer Backed Windows 

Occasionally a client may need to capture the bitmaps created by procedures in the Display 
interface rather than having them painted on the screen. This is accomplished by creating 
a special window handle, a Buffer Backed Window, which is passed to procedures in the 
Display interface. This is discussed in greater detail under §59.2.9. 

59.2 Interface Items 

59.2.1 Basic Data Types and Utility Operations 

This section describes basic Window data types and utility procedures. 
Handle: type « long pointer to Object; 
Object: TYPE [191; 

Object is the storage that represents a window. A Handle is used to refer to the window. 
Clients should not allocate objects directly but must use operations described in §59.2.2. 

rootWindow: readonly Handle; 

Root: PROCEDURE RETURNS [Handle] > iNUNE {RETURN[rootWindow]}; 

rootWindow is the window that is the root of the window tree. The procedure Root is 
provided for compatibility with previous versions; new applications should use 
rootWindow instead. 

MinusLandBitmapUnder: type [6]; 

MinusLandBitmapUnder is additional storage for windows that may have bitmap>unders. 
MinusLandColor: type [1]; 

MinusLandCoior is not used in the current release. 
MinusLandCookleCutter: type [2]; 

MinusLandCookieCutter is not used in the current release. 
Place: type ■ Us«rT«rminai.Coordmate; — fx, y: integer]; 

Place is a position in a window. It is measured relative to the window's upper-left corner, 
which is defined to be at [x: 0, y: OJ. x increases to the right, y increases downward. Note 
that the coordinates may be negative. 

Dims: type - record [w, h: integer]; 

Dims is the size of a rectangular box. The rectangle is w pixels wide and h pixels high. 
Box: type a record [place: Place, dims: Dims]; 
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BoxHandle: type » long pointer to Box; 
nuilBox: Box ■ [place: [0,0], dims: [0,0]]; 

Box describes completely a rectangular box. place describes the upper-left pixel of the box, 
and dims describes the size of the box. The box extends to the right and downward from 
place. As always, place is expressed in its containing Mondow's coordinate system. 

BoxesAreOisjoInt: procedure [a, b: Box] returns [boolean]; 

BoxesAreOisjoint returns true if a and b do not intersect. 

IntersectBoxes: procedure [b1 , b2: Box] returns [box: Box]; 

IntersectBoxes returns a Box that is the intersection of b1 and b2. If their intersection is 
empty, this operation returns box.dims ■ [0, 0]. 

IsPlaceinBox: procedure [place: Place, box: Box] returns [boolean]; 

IsPlacelnBox returns true if place is a pixel of box. 

BitmapPlace: procedure [window: Handle, place: Places [0,0]] returns [Place]; 

BitmapPlace returns the coordinates in the root window that correspond to place in 
window. 

BitmapPlaceToWindowAndPlace: procedure [bitmapPlace: Place] 
RETURNS [window: Handle, place: Place]; 

BitmapPlaceToWindowAndPlace returns the topmost visible window and the coordinates 
within it that correspond to bitmapPlace in the root window. 

59.2.2 Window Creation and Initialization 

A window is created by the client allocating and initializing a window.Object. Many times 
windows are not created directly by clients, but rather are obtained from various other 
facilities, such as StarWindowSheil or Form Window. 

To create a window, the client allocates a window.Object using New, initializes it using 
Initialize, and presents it to Window for use using InsertlntoTree. When the window is of 
no further use, it is withdrawn from Window using RemoveFromTree, and the storage is 
freed using Free or FreeTree. 

New: procedure [ 

under, cookie, color: boolean ^ false, zone: uncounted zone *-hil] returns [Handle]; 

New allocates a window object. If zone is nil, a cache of objects is used. A client should 
never call zone. NEw[window. Object] because the window object will not be properly 
initialized. 
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Initialize, InitiaiizeWindow: procedure [ 

window: Handle, display: OispiayProc, box: Box, 
parent: Handle rootWindow, sibling, child: Handle nil, 
ciearingRequired: boolean ^ true, windowPane: boolean <- false, 
under, cookie, color: boolean <~ false]; 

OispiayProc: type « procedure [window: Handle]; 

Initialize and InitiaiizeWindow Initialize the window object at window f . This must be 
done before the window is inserted into the window tree. The window is initially not a part 
of the window tree. It may be created as an Isolated window or may be linked to other 
private windows to form a private tree.dispiay is the client procedure for repainting the 
window, box is the window's size and parent-relative location, parent is the window's 
parent, sibling is the sibling immediately below the window in the sibling stack of parent 
and child is the top child of the window, parent, sibling, and child may be nil. 
ciearingRequired is described in §59.1.3. windowPane is described in §59.1.4. under 
indicates that the window can be associated with a bitmap-under. cookie and color are not 
supported in the current release; clients should default this parameter for compatibility 
with future versions. 

Create: procedure [ 

display: OispiayProc, box: Box, 

parent: Handle 4-rootWindow, sibling, child: Handle <-nil, 
ciearingRequired: boolean 4- true, windowPane: boolean false, 
under, cookie, color: boolean false, zone: uncounted zone «~nil] 
returns [Handle] ■ inline...; 

Create is an inline that follows a call to New with a call to Initialize. 

Free: procedure [window: Handle, zone: uncounted zone <-nil]; 

Free frees a window object. If zone is nil, the window is returned to the cache of objects 
maintained by Window; otherwise it is freed to the zone. Any contexts associated with the 
window, via the Context interface, are not freed. Free may raise Error(invaiidParametersl if 
the window had already been freed, if the window is still in the window tree, if the zone is 
NIL but was not nil on the call to New, or if the zone is non-NiL but was nil on the call to New. 

FreeTree: procedure [window: Handle, zone: uncounted zone *^ nil]; 

FreeTree frees the window and all its children, children first, and frees all contexts on 
windows in the subtree whose root is window.. Clients should almost always call FreeTree 
rather than Free. FreeTree may raise Error[invalidParameters] if the windows had already 
been freed, if the windows are still in the window tree, if the zone is nil but was not nil when 
the windows were allocated, or if the zone is non-NiL but was N|L when the windows were 
allocated. FreeTree assume all the windows were allocated with the same zone if it is non- 

NIL. 
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59.2.3 Access to and Modification of a Window's Properties 

The Get procedures below return properties of a window. The Set procedures change 
properties and return the previous value. These properties of a window are described in 
this chapter's overview. 

GetOispiayProc: procedure [Handle] returns [DisplayProc]; 

SetOisplayProc: procedure [Handle, OispiayProc] returns [DisplayProc]; 

GetClearingRequired: procedure [Handle] returns [boolean]; 

SetCearingRequired: procedure [window: Handle, required: boolean] 
RETURNS [old: boolean]; 

GetParent: procedure [Handle] returns [Handle]; 

GetSibling: procedure [Handle] returns [Handle]; 

GetSibling returns the next lower sibling of the argument window. 

GietChild: procedure [Handle] returns [Handle]; 

GeKhild returns the topmost child of the argument window. 

See also §59.2.4 for Set procedures that change a window's links to its parent, siblings, and 
child. 

EntireBox: procedure [Handle] returns [Box]; 

EntireBox returns the box [[0, 0], window.dims]. It is handy for invalidating the entire 
window. 

GetBox: procedure [Handle] returns [Box]; 

Note that there is no SetBox; SlldeAndSize should be used instead. 
GetPane: procedure [Handle] returns [boolean]; 

GetPane returns whether or not the window is a window pane. The window pane property 
can only be set when the window is initialized. 

IsCookleVariant: procedure [Handle] returns [boolean]; 

Cookie cutters are not supported by the current release. IsCookie Variant should always 
return false. 

IsColorVariant: procedure [Handle] returns [boolean]; 

Color is not supported by the current release. IsColorVariant should always return false. 
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59.2.4 Window Tree and Window Box Manipulation 

Basic operations are provided for constructing private trees from private windows and for 
inserting them into and removing them from the window tree. Other operations allow 
moving a window within a window tree and changing a window's location and size. Special 
operations are provided to perform common combinations of these operations. 

Most clients obtain windows from some higher-level facilitiy like Form Window; in such 
cases, the window typically has already been inserted into the window tree. Thus most 
clients will only use the following operations: Stack, Slide, SlideAndStack, SiideAndSize, 
SiideAndSizeAndStack. 

Unless otherwise noted, all these operations may be applied either to windows in the 
window tree or to windows in a private tree. Operations performed on windows in private 
trees change tree links and the window's box but naturally create no invalid regions on the 
display. 

As described in the overview, none of the operations in this section perform screen 
painting. They merely enqueue painting work to be performed by a later Validate 
operation. 

lsO€scendantOfRoot: procedure [Handle] returns [boolean]; 

IsOescendantOf Root returns true if window is currently a part of the window tree. 

ObscuredBySibling: procedure [Handle] returns [boolean]; 

ObscuredBySibling returns true if the box of any higher sibling intersects window's box. 

EnumerateTree: procedure [root: Handle, proc: procedure [window: Handle]]; 

EnumerateTree calls proc for every window in the tree rooted at root. The order of 
enumeration is not specified. Altering the tree while an enumeration is in progress^ causes 
unpredictable operation. 

The following three operations allow constructing private trees from private windows. 

SetParent: procedure [window, newParent: Handle] returns [oidParent: Handle]; 

SetSibling: procedure [window, newSibling: Handle] returns [oldSibling: Handle]; 

SetChild: procedure [window, newChild: Handle] returns [oldChild: Handle]; 

These Set procedures set the parent, next lower sibling, or topmost child of window. No list 
manipulation nor consistency checking is done-these operations merely store their 
argument into the window object. If window is in the window tree, Error(windowlnTree] is 
raised (Stack, et al. can be used in that case). If inconsistent calls to the Set procedures are 
made, Error[windowNotChildOfParent] is raised when some subsequent operation detects 
the inconsistency. 

InsertlntoTree: procedure [window: Handle]; 
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InsertlntoTree inserts a private window or subtree into any window tree, window is 
inserted as a child of window.parent. window is immediately above window.sibling in 
the sibling stack of the new parent; window.sibling » nil makes it the bottom most sibling, 
window.child is the topmost child of a private tree that descends from the window— nil if 
none. All of these fields of window may be set by using the Set procedures described above. 
The client can force painting of the windows just inserted by doing 
window.G€tParent(].ValidateTreen. Error(noSuchSibling] may be raised. Fine point: 

InstftlntorrM does not normally cause any painting activity. However, if a window that has a bitmap- under is 
inserted into the tree and the content of the bitmap is not available on the display. Validate Tree is done on that 
window's parent to obtain the content of the bitmap. 

RemoveFromTree: procedure [Handle]; 

RemoveFromTree removes the window and all of its descendants from its containing tree. 
The window becomes the property of the client. The descendants of the window remain 
attached to it. The entire subtree may be later inserted back into a tree by using 
InsertlntoTree. The client can force painting of now-incorrect areas of the display by 
applying ValidateTree to any parent of the removed window. Caution: The sibling pointer 
of the removed window remains pointing to its former sibling in the tree. A client should 
take care that the sibling pointer of the window is set to the desired, valid in-tree sibling (or 
NIL) before doing a subsequent InsertlntoTree. 

Stack: procedure [window: Handle, newSibling: Handle, newParent: Handle <~ nil]; 

Stack changes window's location in its window tree, thus changing the window's depth in 
the apparent stack of windows on the screen. If newParent is not nil, then window is 
moved to be a child of newParent; otherwise, its parent is unchanged. Next, the sibling 
stack then containing window is modified so that window is now immediately above 
newSibling, thus potentially obscuring siblings lower on its sibling stack. Supplying 
newSibling a nil puts window on the bottom of the sibling stack. Unless window is 
already the top sibling, supplying newSibling « window.GetParent.GetChild[] puts 
window on the top of the stack. Caution: If window is the top sibling, the previous 
expression is a client error that is not guarded against. If one of window or newParent is in 
the window tree but the other is not, Error(illegaiStack] is raised. Error[noSuchSibling] may 
also be raised. 

Slide: procedure [window: Handle, newPlace: Place]; 

Slide changes window's position relative to its parent. This procedure may be used to 
implement scrolling. Error(whosSiidingRoot] may be raised. 

SlideAndStack: procedure [ 

window: Handle, newPlace: Place, newSibling: Handle, newParent: Handle nil); 

SlideAndStack performs a Stack and then a Slide, thus changing window's location in its 
tree and its position within its new parent. Error[illegalStack], Error[noSuchSibling], and 
Error(whosSlidingRoot] may be raised. 

Gravity: type ■ {nil, nw, n, ne, e, se, s, sw, w, c, xxx}; 
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Gravity indicates where the old pixel content of a window should go when it changes size. 
This allows Window to reuse any current window content that will be visible in its new 
configuration. 

nil The contents remain at their current screen position (not 

their window-relative position). 

nw, n, M, e, se, s, sw, w The contents stay attached to the Indicated compass point of 

the window, which is either a comer or the middle of a side; 
for example, nw means the contents stay in the upper- left 
corner. 

c The contents go in the middle of the new window-trimming 

or expansion occurs equally at opposite edges. 

XXX The contents are discarded. 

SiideAndSize: procedure [window: Handle, newBox: Box, gravity: Gravity nw]; 

SiideAndSize changes both the location and size of window, gravity indicates what to do 
with the current contents of the window. ErrorfsizingWithBitmapUnder] and 
Error(whosSiidingRoot] may be raised. 

SlideAndSizeAndStack: procedure [ 

window: Handle, newBox: Box, newSibiing: Handle, newParent: Handle NIL, 
gravity: Gravity ^ nw]; 

SlideAndSizeAndStack performs a Stack and then a SiideAndSize, thus changing 
window's location in its window tree and its position and size within its new parent. 
Error[illegaiStack], Error[noSuchSibling], Error[sizingWithBitmapUnderl, and 
Error[whosStidingRoot] may be raised. 

Slidekonicaily: procedure [window: Handle, newPlace: Place]; 

Slidelconicaily is not implemented in the current release. 



59.2.5 Causing Painting 

A general description of painting is given in §59.1.3. The procedures below are used both to 
cause areas of the screen to be painted and actually to do the painting. 

InvalidateBox: procedure [window: Handle, box: Box, clarity: Clarity <~ isOirty]; 

Clarity: type ■ {IsClean, isOirty}; 



InvalidateBox declares that the current screen content of box in window is incorrect. 
Window adds box to the list of invalid regions of the window, clarity indicates the current 
state of the box. clarity ■ isClean means the region is already erased (all white); isOirty, 
that it contains some black. Window uses this information to avoid unnecessary clearing. 
InvalidateBox does not cause immediate display painting; only the Validate procedures do 
that. Note that a call on InvalidateBox followed by a call on Validate may result in no call 
to the display procedure-for e.xample, if the Invalidated area is not visible. If the window is 
not in the window tree, this operation does nothing. 
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Validate: procedure [window: Handle]; 

VaiidateTree: procedure [window: Handle rootWindow]; 

Validate and VaiidateTree are the only Window procedures that cause immediate display 
painting. Fine point: The few special cases that do not follow this rule are noted in the text. Validate acts 
only on window; VaiidateTree acts on the tree whose root is window. Typically, a client 
updates its data structures and invalidate various regions. When the client is ready to have 
the display updated, one of the Validate procedures is called. If window is not in the 
window tree, this operation does nothing. 

EnumerateinvalidBoxes: procedure [window: Handle, proc: procedure [Handle, Box]]; 

EnumeratelnvaiidBoxes is used within a window's display procedure to obtain the list of 
invalid regions of the window. EnumerateinvalidBoxes calls proc for each of the invalid 
boxes of window; window is passed to proc as its first argument. The second argument of 
proc describes the region that is invalid. Note: A display procedure need not worry about 
redundant painting outside the invalid regions; Window automatically discards the 
display procedure's paint that falls outside the invalid regions. This operation must only be 
called from within a display procedure, and window must be the window argument of the 
display procedure. 

FreeBadPhosphorList: procedure [window: Handle]; 

In special circumstances, a display procedure may wish to paint into valid visible areas. 
FreeBadPhosphorList deletes the display procedure's invalid area list; for the lifetime of 
that invocation of that display procedure, paint requests are clipped only to the visible 
parts of the window. This operation must only be called from within a display procedure, 
and window must be the window argument of the display procedure. 

TrimBoxStickouts: procedure [window: Handle, box: Box] returns [Box]; 

TrimBoxStickouts returns a box that is the result of excluding any portion of box that 
sticks out of window or its ancestors. Display procedures may find it useful. 

59.2.6 Errors 

Error: error [code: ErrorCode]; 

ErrorCode: type « { 

illegalBitmap, iilegalFloat, windowNotChildOfParent, whosSlidingRoot, 
noSuchSibling, noUnderVariant, windowlnTree, sizingWithBitmapUnder, 
illegalStack, invalidParameter}; 

illegalBitmap A window passed to SetBitmapUnder is not totally visible. 

iilegalFloat See Float. 

WindowNotChildOfParent A window is not in the list of its parent's children. This 
"^^1^ usually means that inconsistent calls to SetParent, 

SetChild, or SetSibling were made. 
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whosSlidingRoot 
noSuchSibiing 

noUnderVariant 

window! nTree 

sizingWithBitmapUnder 

iilegaiStack 

invaiidParameter 



The client has attempted to move the root window. 

An operation moving a window in the window tree specifies 
a new sibling that is not a child of the new parent. 

A bitmap under operation was applied to a window that 
may not have a bitmap-under associated with it. 

SetParent, SetSibiing, or SetChiid was applied to a window 
in the window tree. Stack, et al., can be used instead. 

A client has tried to change the size of a window that 
currently has a bitmap-under but does not have an 
Allocate Under Proc or a FreeUnderProc associated with it. 

The client is attempting to move a window between 
parents, one of which is in the window tree and the other is 
not. 

The client has invoked an operation with invalid 
parameters. 



59.2.7 Special Topic: Bitmap-Under 

Bitmap-unders are described in §59.1.4. Most clients have no need for bitmap-unders. 
IsBitmapUnderVariant: procedure [Handle] returns [boolean]; 

IsBitmapUnderVariant returns true if the window can be associated with a bitmap-under 
(that is, if lnitializeWindow{ . . . , under: true]). 

WordsForBitmapUnder: procedure [window: Handle] returns [cardinal]; 

WordsForBitmapUnder returns the number of words of storage needed for a bitmap-under 
corresponding to the current size of window. PagesForBitmapUnder should be used rather 
than WordsForBitmapUnder because pages are a more appropriate unit to describe 
bitmap-unders and large bitmap-unders can exceed the number of words which can be 
returned from WordsForBitmapU nder . 

PagesForBitmapUnder: procedure [window: Handle] returns [long cardinal]; 

PagesForBitmapUnder returns the number of pages of storage needed for a bitmap-under 
corresponding to the current size of window. This procedure should be used rather than 
WordsForBitmapUnder because pages are a more appropriate unit to describe bitmap- 
unders and large bitmap-unders can exceed the number of words that can be returned from 
WordsForBitmapUnder . Fine Point: This procedure is currently exported through WindowExtra . 

PagesForOims: procedure [dims:Oims] returns {long cardinal]; 

PagesForOims returns the number of pages of storage needed for a bitmap-under 
corresponding to a window with dimensions of dims. This procedure is useful when a 
window has not yet been created, yet the size of the required bitmap is desired. This is 
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useful when using CreateBufferBacked (see §59.2.9). Fine Point: This procedure is currently 
exported through WindowExtra. 

SpeciaiSetBitmapUnder: procedure [ 
window: Handle, 

ailocateUnder: AllocateUnderProc, 
freellnder: FreeUnderProc]; 

AllocateUnderProc: TYPE« procedure [pages: LONG CARDINAL] RETURNS [pointer: LONG 
POINTER); 

FreeUnderProc: TYPE ■ procedure {pointer: LONG POINTER]; 

SpeciaiSetBitmapUnder associates an AllocateUnderProc and a FreeUnderProc with 
window. aiiocateUnder is the client's procedure for allocating scratch storage area for 
window's bitmap-under. freeUnder is the client's procedure for freeing window's bitmap- 
under storage when it is no longer needed. aiiocateUnder and freeUnder are called during 
insertion and removal of window to and from the visible window tree as well'as in sliding, 
stacldng and moving of window. 

Unlike SetBitmapUnder, SpeciaiSetBitmapUnder allows the Window implementation to 
get bitmap-under storage through the client's AllocateUnderProc during the life of the 
window and thus provides flexibility of bitmap-under storage size and allows the sizing of 
bitmap-under windows. 

Note that the client is responsible for the actual allocation and freeing of space. The 
client's AllocateUnderProc should return NIL if there is not enough resources to provide 
window with a bitmap-under. If the AllocateUnderProc returns NIL, window ceases to 
have a bitmap-under until the next time the AllocateUnderProc is called and some space is 
returned. 

If the window cannot be associated with a bitmap-under, Error[noUnderVariantl is raised. 
For window to be associated with a bitmap-under, it must be created through 
New(...under: TRUE] and lnitialize[...under:TRUE]. Fine Point: This procedure is currently exported 
through WindowExtra. - 

GetAllocateUnderProc: procedure [window:Handle] RETURNS [aiiocateUnder: 
AllocateUnderProc] ; 

GetAllocateUnderProc returns the AllocateUnderProc associated with window. If 
window does not have an AllocateUnderProc, GetAllocateUnderProc returns NIL. Fine 
Point: This procedure is currently exported through WindowExtra. 

GetFreeUnderProc: procedure [window: Handle] RETURNS [freeUnder: FreeUnderProc]; 

GetFreeUnderProc returns the FreeUnderProc associated with window. If window does 
not have a FreeUnderProc, GetFreeUnderProc returns NIL. Fine Point: This procedure is 
currently exported through WindowExtra. 
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SetBitmapUnder: procedure [ 

window: Handle, pointer: long pointer nil, 
underChanged: UnderChangedProc 4-nil, 

mouseTransformer: MouseTransformerProc f-Nii] returns [long pointer]; 
UnderChangedProc: type ■ procedure [Handle, Box]; 

MouseTransformerProc: type • procedure [Handle, Place] returns [Handle, Place]; 

SetBitmapUnder associates a bitxnap-under with window, pointer describes a scratch 
storage area for the bitmap- under; its length must be as given by WordsForBitmapUnder. 
If pointer * nil, the window ceases to have a bitmap-under. The pointer to any previous 
bitmap-under is returned; the client becomes the owner of that storage. The underChanged 
and mouseTransformer parameters are ignored in the current release. If the window 
cannot be associated with a bitmap-under, Error[noUnderVariant] is raised. If the window 
is in the window tree but is obscured by another window, Error[illegai Bitmap] is raised. 
While the bitmap-under is in effect, the window's size cannot be changed; an attempt to do 
so will raise Error[sizingWithBitmapUnder]. 

GetBitmapUnder: procedure [window: Handle] returns [long pointer]; 

GetBitmapUnder returns the pointer to the current bitmap-under for window; returns nil 
if none. If the window cannot be associated with a bitmap-under, Error[noUnderVariant] is 
raised. 

Float: procedure [window, temp: Handle, proc: FioatProc]; 

FloatProc: type » procedure [window: Handle] returns [place: Place, done: boolean]; 

Float moves a window continuously on the screen. Float first forces window to the top of its 
sibling stack, next does ValidateTree(rootWlndow], and then enters a loop for changing 
the window's position. In the loop, Float calls proc, passing window to it. If proc returns 
done ■ TRUE, the operation terminates and Float returns to the client. Otherwise, Float 
moves the window to place and repaints the display. It does so without calling any client 
display procedure; control returns to the top of the loop. The client must ensure that the 
window is wholly visible when moved to place, temp is used for temporary storage for the 
duration of the float operation, temp must be the same size as window, have a bitmap- 
under, and not be in the window tree. If window is not in the window tree, if temp is in the 
window tree, if either window lacks a bitmap-under, or if the windows have different sizes, 
Error(iliegalFloat] is raised. 

39.2.8 Special Topic: Linked Windows 

When windows are linked together they form a set. Whatever is painted into one member 
of the set will be painted into all members of the set. Painting is clipped to the visible area 
for each window. The client will usually want to associate the same DisplayProcs and 
TIP.NotifyProcs with each window. Also, if these procedures use Context data then the 
same context should be set for each window. A window may be removed from its set by 
calling the Unlink procedure, or it will automatically be removed when the window is jilli, 
destroyed. Example 2 under Usage/Examples shows typical usage. ' 
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Link: procedure [new, after: Handle]; 

Link associates the new window witJi tiie after window. If after is already a member of a set 
of linlced windows, tlien new will become a member of that set also. Otherwise, new and 
after will become a new set. A window may be a member of only one set. If new is already 
in a set, Error[invaiidParameterl will be raised. Windows which are to be Linked are 
created just as any other window. Each set of linked windows are kept in a circularly 
linked list in the order specified by the client.This means that the new window will be 
inserted into the list following the after window. Fin« Point: This procedure is currently exported 
through WindowExtra. 

Uniink: procedure [window: Handle]; 

Unlink removes window from the set of linked windows it currently belongs to. If it is not a 
member of a set, then nothing happens. Fine Point: This procedure is currently exported through 
WindowExtra. 

GetNextLink: procedure [window: Handle] returns [next: Handle]; 

GetNextLink returns the next window in the set following window. If there are no windows 
linked to window then NIL will be returned. Because the windows are kept in a circular 
list, it is necessary for the client to check the window returned against the window first 
passed to GetNextLink in order to determine when all members of the list have been 
enumerated. This is demonstrated in Example 2. Fine Point: This procedure is currently exported 
through WindowExtra. 

IsLink: procedure [window: Handle] returns [yes: BOOLEAN]; 

IsLink returns returns TRUE if window is currently linked to any other window. Fine Point: 
This procedure is currently exported through WindowExtra. 



59.2.9 Special Topic: Buffer Backed Windows 

Buffer Backed windows provide a method of capturing the bitmaps created by procedures 
in the Display interface. This type of window must not be passed to any procedure in the 
Window interface except, FreeBufferBacked, GetBox and EntireBox or unpredictable 
results will occur. The client is responsible for flushing the backing buffer before painting 
into it - Display.White is one method. Example 3 under Usage/Examples shows a typical 
client. 

CreateBufferBacked: procedure [ 
dims: Dims, buffer: long pointer, 

cookie, color: boolean *- false, zone: uncounted zone<- nil] 

returns [window: Handle, paintAddress: Environment.BitAddress, bpl: natural]; 

CreateBufferBacked creates a window which will have dimensions corresponding to the 
dims parameter. The backing buffer pointed to by buffer must be of at least the size 
specified by PagesForOims. The first return value, window, can be passed to any procedure 
in the Display interface. The bits will be painted into the backing buffer rather than onto 
the display. The second value returned, paintAddress, points to the first bits in the buffer 
which will be painted. This may differ from the value of buffer for alignment reasons. The 
third value returned, bpl, specifies the bits per scan line. The cookie, color and zone 
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parameters have the same meaning as in the New and Initialize procedures. This window jmi^ 
must be freed by calling FreeBufferBacked rather than Free. Fine Point: This procedure is 
currently exported through WindowExtra. See Usage/ExampleS. 

FreeBufferBacked: procedure [window: Handle, zone: uncounted zone 4> nil]; 

FreeBufferBacked will free the window. The client must free the backing buffer. The zone 
parameter has the same meaning as in the Free procedure. Fine Point: This procedure is currently 
exported through WindowExtra. 

59.3 Usage/Examples 

A scrollbar is an example of a simple window. An entire StarWindowShell window is an 
example of a window that has many descendant windows — the window header, the 
scrollbars, and the main interior window used to display the content. 

Window shields the client from interference between windows and from the presence of the 
edges of the display screen. A client can freely move a window around on or off the screen 
and alter its position in the stack of windows; Window automatically handles the 
overlapping. 

Window automatically clips painting into windows to the visible interior of its parent 
window. A client can freely paint anywhere inside or even outside of its window as 
convenient. 

It is always correct to paint more of a window than the minimum required. Simple clients 
may adopt a simple repaint strategy, invalidating and/or repainting a large part or even all 
of a window. Sophisticated clients may invalidate only the necessary parts of a window, 
thus allowing only small amounts of repainting and minimizing references to the window's 
backing data. This may result in improved performance. 

A display procedure has available to it a list of invalid areas that need to be repainted. 
However, it may adopt the simple approach of ignoring this data and repainting the entire 
window. In any case. Window clips a display procedure's paint to the boundaries of the 
invalid regions. 

Areas that project outside of a window's parent are trimmed for display purposes. Vertical 
scrolling can be implemented quite simply by embedding a tall content window in a short 
clipping window and then just Slideing the position of the content window within the 
clipping window. Horizontal scrolling can be done in a similar way. The StarWindowShell 
interface supports this method of scrolling. This approach is limited by the domain of the 
coordinates, which are integers. Scrolling in this way is limited to +-2 1 15 pixels offset 
from the frame window. If more scrolling than this is required, the client cannot use this 
technique, but must itself perform the transformation from data coordinates to window 
coordinates. 

Since a window's location is defined in its parent window's coordinate system, moving a 
window automatically moves all of its descendant windows along with it. 

Window itself has nothing to do with the keyboard and mouse. However, the TIP interface 
provides the facility for associating mouse and keyboard actions with a window. 
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59.3.1 Display Procedures and monitors 

Any process may manipulate windows and thus cause screen painting activity. Even if one 
client always runs in the Notifler process, its window's display procedure may be called at 
any instant because of asynchronous activities by some other process. If a window's display 
procedure uses any nonlocal variables in its painting activity (the usual case), those 
variables must be protected by a MONITOR. Most display procedures are monitor entry 
procedures. Of course, if the display procedure only refers to immutable data, its operation 
need not be monitored. 



Since a display procedure is usually a monitor entry, the client must avoid deadlocks by not 
invoking the display procedure from within other monitor procedures. This is the standard 
rule for monitors. Because calling Validate may cause Window to call the client's display 
procedure, calls to Validate must be done outside the client's monitor. The normal 
arrangement is (I) enter monitor, (2) update monitor data and Invalidate regions, (3) exit 
monitor, (4) Validate (which causes the display to be repainted). 



59.3.2 Example 1 

— These excerpts are taken from <BWSHacks> 1.0>SQurce>Puzzle1SlmpLmesa 

boxSize: CARDINAL • 32; 

boxDims: wiiidow.Dims « [boxSize, boxSize]; 

bodyWindowDims: window.Dims a [boxSize*grid + 2, boxSize*grid * 2]; . 
boxes: ARRAY [0..max) OFwindow.Box; 



MenuProc: MenuOata.MenuProc ■ { 

rb: xstring.ReaderBody «~xstring.FromSTRIN<3("15 Puzzle"L]; 
shell: starWindowSheii.Handle « starWindowSheii.Create [name: @rb]; 
— Window.lnitiallzeO is called by StarWindowSheU Impls. 
body: window.Handle • starWindowSh«ii.CreateBody [ 
sws: shell, 

box: [[0,0],bodyWindowOims], 
repaintProc: Redisplay, 
bodyNotifyProc: NotifyProc]; 



StarWIndowShelLPush [shell]; 

}; 

NotifyProc: tip. NotifyProc ■ { 

data: Data <- Local Ft nd(window]; - C/se Context to find data for this instance. 
place: window.Ptace; 

FOR input: TiP.Results 4- results, input.next until input ■ nil do 
WITH z: input select from 
coords ■ > place <- z.place; 
atom a > SELECT z.a from 
pointUp • > { 
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box: CARDINAL 4- ResolveToBox [place]; 
IF Adjacent [data. empty, box] then { 

Window.! nvaiidateBox [window, boxes(data.empty]]; 

window.lnvaiidateBox [window, boxes(box]]; 

SwapBoxWithEmpty [data, box]; 

Window. Vaiidate(window]; 

}; 

}; 

enocase; 
enocase; 



Redisplay: PROC [window: window.Handle] ■ { 

— This is the body window's dispiay procedure. 

data: Data «- LocalFind(window]; ~ Use Context to find data for this instance. 
vertical: Window. Dims <- [2, boxSize*gridl; 
horizontal: window.Oims [boxSize*grid, 2]; 
place: window.Place [0.0]; 

— Dispiay the 15 numbers 
FOR i: CARDINAL IN [0..max} DO 

value: cardinal 4- data.values(i]; 

The bitmaps were created eariier (not shown in this example) 
oispiay.Bitmap [window, boxes[i], [@bitmaps(value],0,0], boxSize]; 

ENOLOOP; 

— Dispiay the vertical lines 

FOR i : cardinal in [0..grid -!> 2) DO 

Dispiay.Black [window, [place,vertical]]; 
place.x <~ place.x * boxSize; 
enoloop; 

— Display the horizontal lines 
place 4- [0,01; 

FOR i: CARDINAL IN [0..grid > 2) DO 

Dispiay.Black [window, [place,honzontal]]; 
piace.y 4- place.y * boxSize; 

ENOLOOP; 

}; 

- Register a command for invoking this tool 
I nit: PROC ■ { 

rb: xstring.ReaderBody ^-xstring.FromSTRINGClS Puzzle^L]; 
StarD«sl(top.AddltemToAttentionWindowMenu [ 
MenuOata.Createltem [ 

zone: Heap.systemZone, 

name: @rb, 

proc: MenuProc] ]; 



}; 
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59.3.3 Example 2 

— This example demonstrates one simple use of Linked Windows. 

— How to Link windows 

AddSpiitWindow: PROC [currentWindow: Window.Handle] a { 

new: Window.Handle ^StarWindowSheli.CreateBody[...]; - Create a window 
displayProc: Window.OispiayProc Window.GetDisplayProc[currentWindow]; 
notifyProc: TIP.NotifyProc <-"nP.GetNotifyProc(currentWindow]; 
Q <-> Window.SetDisplayPrpc[new, displayProc]; 
[] «- TIP.SetNotifyProc[new, notifyProc]; 
Wi ndowExtra.Li nk[new, currentWindow] ; 

}; 

— How to Unlink windows 

RemoveSplitWindow: PROC [currentWindow: Window.Handle] a { 
[] 4~Window.SetOi5piayProc(currentWindow,NiL]; 
I] «-TIP.SetNotifyProc{new,NIL]; 
Wi ndowExtra. U ni i nic[currentWi ndow] ; 

}; 

— How to enumerate windows, 

ActionProc: TYPE ■ PROCEDURE (w: Window.Handle]; 

EnumerateUnkedWindows: PROC [currentWindow: Window.Handle, proc: ActionProc] 
-{ 

— Start with 'currentWindow' and call 'proc' with each window. 

" Note that we start with the window following currentWindow and 

finish with currentWindow. 
firstWindow, nextWindow: Window.Handle: 
IF NOT WindowExtra.lsLlnk[currentWindow] THEN RETURN; 
firstWindow WindowExtra.GetNextLink[currentWindow]; 
FOR nextWindow 4- firstWindow, WindowExtra.GetNextLink[nextWindow] 00 
proc[nextWindow]; 

IF nextWindow m currentWindow THEN EXIT; 
ENDLOOP; 

}; 

59.3.4 Examples 

— This is a very simple example of how to create an image in a Buffer Backed Window 

— and then paint it onto the screen. The image could be processed differently. 

mainWindow: Window.Handle; 
bbWindow: Window.Handle NIL; 
paintAddress: Environment.BitAddress; 
bpl: NATURAL; 

dims: Window. Dims « [w: 800, h: 800]; ^ For example 
pages: LONG CARDINAL; 
backingBuffer: LONG POINTER; 
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-- Create the window where the resulting bitmap will be painted. ^ga^ 
Note: The bits could be copied to another source. 
mainWindow *- 

- Allocate the buffer to back the window 
pages 4- WindowExtra.PagesForOims[dims]; 

backingBuffer: LONG POINTER *~ Space.ScratchMap(count: pages]; 

- Create the Buffer Backed Window 

/bbWindow, paintAddress, bpil WindowExtra.CreateBufferBacked( 
dims: dims, buffer: backingBuffer]; 

— Clear the "window" (i.e. the buffer) 

Display .White(window:bbWindow, box: Wlndow.GetBox[bb Window]]; 

Paint something into the "window" (i.e. the buffer) 
Oisplay.Biack[ 

window:, bbWindow 
box: ...]; 

— Write the prepared image onto the screen inside 'mainWindow' 
Oisplay.Bitmap( 

window: mainWindow, 
box: [...], 

address: paintAddress, jiii^ 
bitmapBitWidth: bpi]; 

Cleanup 

backingBuffer Space.Unmap(backingBufferl; 
Wl ndowExtra.Ff eeBuff erBacked[bbWi ndow] ; 



59.3.5 Example 4 

- 77i/5 example demonstrates how to create, display and destroy a bitmap' under 
window. 

CreateWindow: PROCEDURE RETURNS [window: Window.Handle] « { 
window Window. New[under: under]; 
Window.initializeC 
window: window. 



under: under]; 

- if under is TRUE, window can later be associated with a bitmap under but does 

- not necessarily have to if resources are not available. 

- Needs to call both Window.New and Window.lnitialize instead of 

- Window.Create cuz the inline Window.Create does not call Initialize 
~ with the under parameter correctly.}; - 
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}- Create Window 

PushWtndow: PROCE0URE[window: Window.Handie] « { 
IF Window.isBitmapUnderVariant[window] THEN 
[] ^ WindowExtra.SpecialSetBitmapUnder[ 
window: window, 
ailocateUnder: AliocateUnder, 
freeUnder:FreeUnderl; 
Wi ndow.l nserti ntoTree( wi ndow] ; 
Window.ValidateTree Q; 
}; - PushWindow 



DestroyWindow: PROCEDURECwindow: Window: Handle] « { 

Window.RemoveFromTreeCwindow]; 

Window.Free[window]; 

Window. VaiidateTreeQ; 
}; - DestroyWindow 

EnoughBackingFile: PROCEDURE [pagesForBU: LONG CARDINAL] RETURNS [BOOLEAN] 
- { 

- This procedure will return TRUE if we have enough scratch storage in Pilot's 
-anonymous backing file or in the extra backing file to make a bitmap>under. 
-Note this is only an approximation since returning TRUE does not mean that we 
-have enough contiguous space. Pilot might still have to do a File.Create. 

^4^^ RETURN [SpacePerf.countDataPool •SpacePerf.currentUtiiization > pagesForBU 

OR ExtraBackingFiie.countDataPool - ExtraBackingFile.currentUtilization > 
pagesForBU]; 
}; - EnoughBackingFile 

AilocateUnder: WindowExtra.AliocateUnderProc « { 

< <PROCEDURE [pages: LONG CARDINAL] RETURNS [pointer: LONG POINTER] > > 

ENABLE Space.lnsuffidentSpace, Voiume.lnsufflcientSpace « > CONTINUE; 
pointer NIL; 

IF EnoughBackingFile(pages] THEN pointer [Space.ScratchMap[pages]]; 
}; - AilocateUnder 

FreeUnder: WindowExtra.FreeUnderProc « { 

< <PROCEDURE [pointer: LONG POINTERl> > 

[] 4-Space.Unmap(pointer]; 
}; - FreeUnder 
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59.4 Index of Interface Items 



Item 


Page 


Item 


Page 


AliocateUnderProc: type 


13 


IsBitmapUnderVariant: procedure 


12 


BitmapPlace: procedure 


5 


IsCookieVariant: procedure 


7 


BitmapPtaceToWindowAndPlace: procedure 5 


IsCoiorVariant: procedure 


7 


Box: TYPE 


4 


IsOescendantOfRoot: procedure 


8 


BoxesAreOisjoint: procedure 


5 


IsPlaceinBox: procedure 


5 


BoxHandle: type 


5 


IsLink: procedure 


15 


Clarity: type 


10 


Link: procedure 


15 


Create: procedure 


6 


MinusLandBitmapUnder: type 


4 


CreateBufferBacked: procedure 


15 


MinusLandColor: type 


4 


Dims: TYPE 


4 


MinusLandCookieCutter: type 


4 


OispiayProc: type 


6 


MouseTransformerProc: type 


14 


EntireBox: procedure 


7 


New: PROCEDURE 


5 


EnumerateinvalidBoxes: procedure 


11 


null Box: Box 


5 


EnumerateTree: procedure 


8 


Object: type 


4 


Error: error 


11 


ObscuredBySibling: procedure 


8 


ErrorCode: type 


11 


Place: type 


4 


Float: procedure 


14 


PagesForBitmapUnder: procedure 


12 


FloatProc: procedure 


14 


PagesForOims: procedure 


12 


Free:PROCEDURE 


6 


RemoveFromTree: procedure 


9 


FreeBadPhosphorList: procedure 


11 


Root: PROCEDURE 


4 


FreeBufferBacked: procedure 


15 


rootWindow: variable 


4 


FreeUnderProc:TYPE 


13 


SetBitmapUnder: procedure 


14 


FreeTree : procedure 


6 


SetChiid: procedure 


8 


GetAllocateUnderProc: procedure 


13 


SetClearingRequired: procedure 


7 


GetBltmapUnder: procedure 


14 


SetOisplayProc: procedure 


7 


GetBox: procedure 


7 


SetParent: procedure 


3 


GetChild: procedure 


7 


SetSibling: procedure 


8 


GeKlearingRequired: procedure 


7 


Slide: procedure 


9 


GetDispiayProc: procedure 


7 


SlideAndSize: procedure 


10 


GetFreeUnderProc: procedure 


13 


SlideAndSizeAndStack: procedure 


10 


GetNextLInk: procedure 


15 


SlideAndStack: procedure 


9 


GetPane: procedure 


7 


Slidelconically: procedure 


10 


GetParent: procedure 


7 


SpecialSetBitmapUnder: procedure 


13 


GetSibling: procedure 


7 


Stack: procedure 


9 


Gravity: type 


9 


TrimBoxStickouts: procedure 


11 


Handle: type 


4 


UnderChangedProc: type 


14 


Initialize: procedure 


6 


UnLlnk: procedure 


15 


InitializeWindow: procedure 


6 


Validate: procedure 


11 


InsertlntoTree: procedure 


8 


ValidateTree: procedure 


11 


IntersectBoxes: procedure 


5 


WordsForBitmapUnder: procedure 


12 


InvalidateBox: procedure 


10 
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60.1 Overview 

The XChar interface is part of a string package that supports the Xerox Character Code 
Standard^ referred to in this document as the "standard." XChar defines the basic character 
type and some operations on it. 

The standard defines 16-bit characters, which would permit up to 65,536 distinct 
characters. Reserving control character space reduces them to 35,532. It is convenient to 
partition the character code range into 256 blocks of 256 codes each. Each block is called a 
character set. This approach allows a convenient run-encoding scheme. 

All the character sets currently defined are enumerated in XCharSets. 

60.2 Interface Items 

60J2.1 Character Representation 
Character: type ■ word; 
Character is a 16-bit character. 

Fine point: Currently only 16-btt characters are defined by the standard, but larger characters are not precluded. 
If the standard is extended to include more bits per character, the type Character will be redefined. 

CharRep:TYPE » machine dependent record [set, code: Environm«nt.Byte]; 

CharRep is a type that defines the representation of a character as character set and code. 
The operations Code, Make» and Set should be used instead of this type. 

Code: procedure [c: Character] returns [code: Environm«nt.Byte] ; 

Code returns the code within a character set of the character parameter. 

Make: procedure [set, code: Environment. Byte] RETURNS [Character]; 



60-1 



60 XChar 

Make constructs a character, given a character set and a code within the character set. 

Set: PROCEDURE [c: Character] returns [set: Environin«nt.Byte] ; 

Set returns the character set of the character parameter. 

nuii: Character ■ 0; 

not: Character ■ 177777B; 

not is a value that may be used by operations that return a character to signify that no 
characters remain. 

60.2.2 JoinDirectioii and StreakNature 

JoinOirection: type « (nextCharToLeft. nextCharToRight}; 

JoinOirection speciHes whether a character goes left to right or right to left. 

GetloinOirection: procedure [Character] returns [JoinOirection]; 

GetiotnOirection returns the join direction for a character, given its set and code within its 
set. 

ArabicFirstRightToLeftCharCode: Environm«nt.Byte ■ 608; _ 
ArabicFirstRightToLeftCharCode is used by GetloinOirection. 
StrealcNature: type « {leftToRight, rightToLeft}; 
GetStreaicNature: procedure [Character] returns [StrealcNature]; 
Returns a characters StrealcNature (see SimptoTaxtOispiay.StreakSuccession). 

60.2.3 Case 

Oecase: procedure [c: Character] returns [Character]; 

Decase is a case-stripping operation. It returns c with all case information removed. This is 
useful when comparing characters with case ignored. Only characters in character sets 
zero (Latin), 46(Greek), and 47(Cyrillic) are affected. 

Lowercase: procedure [c: Character] returns [Character]; 

LowerCase returns the lowercase representation of the character c. Only characters in 
character set zero (Latin), 46 (Greek), and 47 (Cyrillic) are affected. 

Uppercase: procedure [c: Character] returns [Character]; 

Uppercase returns the uppercase representation of the character c. Only characters in ^^^^^ 
character set zero (Latin), 46 (Greek), and 47 (Cyrillic) are affected. 
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60.3 Usage/Examples 

The following two examples create specific characters. xchar.Make is also useful if the 
character set and code are not known at compile time, but are known at run time. 

60^1 Creating an ASCII Character 

The followini; example creates an ASCII CR character. 

c: xchar.Character 4-xchar.Make{set: xchars«ts.Sets.iatin.0RO, code:LOOPHOLE(Ascii.CR]]; 

60.3.2 Creating a Greek Character 

The following example creates an a from the Greek character set. 

c: xchar.Character <- xaiar.Make(set:xcharS«ts.Sets.greek.0RO, code: 
xcharS«t46.Codes46.1owerAl pha.ORo] ; 
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60.4 Index of Interface Items 



Item Page 

ArabicFirstRightToLeftCharCode: type 2 

Character: type 1 

CharRep: type 1 

Code: procedure 1 

Oecase: procedure 2 

Ge-UoinOirection: procedure 2 

GetStreakNature: procedure 2 

JoinOirection: type 2 

Lowercase: procedure 2 

Make: procedure 1 

null: TYPE 2 

not: TYPE 2 

Set: PROCEDURE 2 

StreakNature: type 2 

Uppercase: procedure 2 



60-4 



XCharSets, XCharSetNNN 



61.1 Overview 

XCharSets enumerates the character sets defined in the Xerox Character Code Standard. 
This chapter also describes a collection of interfaces that enumerate the character codes of 
several common character sets. This collection of interfaces is XCharSetNNN. 

61.2 Interface Items 
61.2.1 Sets 

Sets: TYPE ■ MACHINE DEPENDENT { 

iatin(OK firstUnused1(1) JastUnused1(40B) JisSymbol1(41 B), jisSymbol2(42B), 
extendedLatin(43B), hiragana<44B), katal<ana(45B), greek(46B), cyriilic(47B), 
firstUserKanji1(50B), lastUserKanji1(57B),firstLevel1Kanji(60B)JastLevei1Kanji(117B), 
firstLevel2Kanji(120B), iastLevel2Kanji(163B), jSymbol3(164B), firstUserKanji2(165B), 
lastUserKanji2(176B), firstUnused2(177B). lastUnused2(240B), firstReserved 1(241 B), 
lastReserved1(337B)« arabic(340B)« hebrew(341 B), firstReseryed2(342B), 
lastReserved2(3S5B), generaiSymbols2(356B). generalSymboisI (357B). 
firstRendering(360B), lastRendering(375B)« userOefined(376B), selectCode<377B)}; 

Sets enumerates the character sets. Specific character sets have values defined, such as 
Latin and Hiragana. Character set families such as Kanji and unused or reserved portions 
of the character set enumeration are specified by first and last values; for example, 
firstUserKanjil andlastUserKanjil. 

For those eleven character sets whose codes are specified in the standard, an interface has 
been defined that contains an enumerated type enumerating the codes within the 
character set and a Make procedure that makes a character, given a code literal. 

For example, the interface XCharSet356 has the following definitions: 

Make: procedure [code: Codes356] returns [Character]; 
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Codes356: type « machine dependent { 

thkkSpace(41B), fourEmSpace(42B), hairSpace(43B), punctuationSpace(44B), 
decimalPoint(56B), absoiuteValue(174B), similarTo(176B), escape(377B)}; 

61^2 Enumerationof Character Sets 

Table 61.1 enumerates the eleven character sets whose codes are specified in the standard, 
the interface in which they are contained, and the enumerated type name for that 
interface. 



Character Set 


Interface 


Enumerated Type 


Latin 


XCharSetO 


CodesO 


jisSymboi 1 


XCharSet41 


Codes41 


jisSymboi2 


XCharSet42 


Codes42 


extended Latin 


XCharSet43 


Codes43 


Hiragana 


XCnarSet44 


Codes44 


Kataicana 


XCharSet45 


Codes45 


Greek 


XCharSet46 


Codes46 


Cyrillic 


XCharSet47 


Codes47 


jSymbolS 


XCharSet164 


Codes 164 


arable 


XCharSet340 


Codes340 


Hebrew 


XCharSet341 


Codes341 


general Symbols2 


XCharSet356 


Codes356 


generaiSymbolsl 


XCharSet357 


Codes357 


firstRendering 


XCharSet360 


Codes360 


accented Latin 


XCharSet361 


Codes361 



Table 61.1: Standard Character Sets 



61.3 Usage/Examples 



61.3.1 Creating a Greek Character 

The following example shows two ways to create an a from the Greek character set. 

c: xchar.Character 4-xchar.Make(set:xcharS«ts.Sets.greek.0RD, code: 
xcharS«t46.CGdes46.lowerAlpha.ORo]; 

C: XChar.Character 4~XCharSet46.Make(code: xcharS«t46.Codes46.iowerAipha]; 
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61.4 Index of Interface Items 

Item Page 
Sets: TYPE 1 
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62.1 Overview 

This interface assigns the global handle and message keys for all the messages the system 
requires for system templates (such as time and date formatting, numbers, and so forth.). 
The XMessage interface deals with system messages; it must be understood before using 
this interface. 

62.2 Interface Items 

62.2.1 Obtaining Message Handle 

GetHandle: procedure returns [h: XMessage.Handle]; 

This procedure returns a handle for system-required messages that have already been 
initialized and allocated, and registered by the XComSoftMessage implementation. 

62.2.2 Message Keys 

Keys: type - machine dependent { 
time(O), date(1), dateAndTime(2), am(3), pm(4), january(5), february(6), march(7), 
april(8), may(9), june(10K juiy(11K august(12), september(13), october(14), 
november(1 5), december(16), monday(17), tuesday(18), wednesday(19)« thursday(20), 
friday(21), saturday(22), sunday<23), decimalSeparator(24), thousandsSeparator(25)}; 

time, date, and dateAndTime are available through the XTime interface; they may be used 
as templates in calls to XTim«.ParseReader or xTim«.Append. 

Months: type * Keys [january..december]; 

DaysOfWeek: type > Keys (monday.. Sunday]; 
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62.3 Usage/Examples 

OPEN XCSM: XComSoftMessage; 

systemMsgs: XM«ssag«.Handle 4-xcsM.GetHanclle U: 
mondayString: xstring.Reader <~XM«ssag«.Get [ 
systemMsgs, xcsM.OaysOfWeeic.monday.ORD]; 
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62.4 Index of Interface Items 



Item Page 

GetHandle: procedure 1 

Keys: type 1 

Months: type 1 

DaysOfWeek: type 1 
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XDigits 



63.1 Overview 

The XDigits interface provides the definitions and procedures for implementing and 
manipulating different number representations. 

The average client will only use xoigits.NumberParms that is provided as a parameter for 
certain input/output number routines such as xstringX2.ReaderToNumberX and 
XFormatx.NumberX. 

63.2 Interface Items 

63.2.1 Representation 

Representation :type > machine dependent { 

default(O), ascii(l), arabian(2), persian(3), urdu(4), Jkanji(5), Chanzi(6), 
Khanja(7), amharic(8), burmese(9), khmer(10), lao(ll), thai(12), devanagari(1 3), 
bengaii(14),firstFree(15), last(255)}: 

Representation lists all known number representations. 

Digit: type ■ [0..9]; 

Symbols: TYPE ■ long descriptor for array Digit of xchar.Character; 

Each number representation will have Symbols associated with it. 

NumberParms: TYPE a record [ 
representation: Representation, 
parensForNeg: boolean, 
thousandsSep: xchar.Character]; 

defaultNumberParms: NumberParms « [default, FALSE, xchar.not); 

NumberParms is the parameter for several number input/output routines, representation 
is used to select the symbols to be used to input or output the digits. If representation is 
defaulted, the default representation specified in the User Profile is used. If parensForNeg 
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is TRUE, numbers within parentheses will be accepted and negated on input. On output, if 
parensForNeg is true, negative numbers will be emitted within parentheses instead of the 
minus sign. thousandsSep will be permitted on input provided it is not the first or last 
character. No other checks are made on input. On output, thousandsSep will be emitted 
every three digits. NumberParms is currently a parameter in xstringX2.ReaderToNumberX, 
XTok«nx.NumberX, XTok«nx.DecimaiX, XFormatx.NumberFormatX, XFormatx.NumberX, 
xPormatx.DecimalX, XLRaaixi.ReaderToNumbarX, XLR«aiX2.ReadNumberX and 
XLR«aix2.FornfiatNumberX. 



63.2.2 Operations 

GetSymbois: procedure [representation: Representation] 
RETURNS [symbols: Symbols]; 

GetSymbols returns the symbols associated with representation. If representation does 
not have any symbols associated with it, NIL will be returned. 

SetSymbols: procedure [ 

representation : Representation[ascil ..last], 

symbols: Symbols, 

label: xstring.Reader <~nil] ; 

SetsSymbols sets the symbols for representation . If label is non-NIL, it will replace the 
built-in label for the representation, label will copied and storage for the bytes will be 
allocatedoutof a private zone. jfiiil^ 

SetOefault: procedure [representation: Representation[ascii..last]]; 

SetDefault sets the default representation to be representation. 

GetLabel: procedure [representation: Representation] returns [label: xstring. Reader]; 

GetLabel returns the label for representation. NIL is returned if there is no label for the 
representation. GetLabel does not copy the label but returns a pointer to it. It should not 
be changed by the client. 

63.3 Usage/Examples 



63.3.1 Assigning symbols 



Clients adding a digit representation that has not been implemented will want to use 
SetSymbols. 

AddArabianSymbols: procedure > { 

arabianSymbols: array Digit of xchar.Character <- [ 
xcharSet340.Make[indianO], 
xcharSet340.Make[indian1], 
xcharS€t340.Make[indian2], 
xcharSet340.Make[indian3], 
xcharSet340.1Vlake[indian4], 
xcharSet340.Make[indian5L 
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xcharS«t340.Make[indian6], 
xcharSet340.Make{indian7], 
xcharS«t340.Make[inclian8], 
xcharSet340.Make[indian9]]; 
SetSymbois[representation: arabian, symbols: DESCRiPTOR[arabianSymbois]];}; 



XDigits 



63.4 Index of Interface Items 

Item Page 

defauitNumberParms: NumberParms 1 

Digit: type 1 

GetLabei: procedure 2 

GetSymbols: procedure 2 

NumberParms: type 1 

Representation: type 1 

SetDefault: procedure 2 

SetSymbois: procedure 2 

Symbols: type 1 
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64.1 Overview 

The XFormat package provides procedures for formatting various types into 
xstring. Readers. The procedures require the client to supply an output procedure and a piece 
of data to be formatted. Where appropriate, a format specification is also required. 

64.1.1 Major Data Structures 

The major data structure is the Handie,which points to an object containing a ForrriatProc, 
an xstring.Context.and some ClientOata. All the formatting operations take a handle as the 
destination of the formatted character string. The FormatProc is the main component of an 
Object. It should pass the characters of its reader parameter to the output sink it 
implements and update the object's context to reflect the context of the last character of the 
reader parameter. 

The other major data structure is the NumberFormat, which defines how numbers are to be 
converted to text strings. It includes the base of the number, the number of columns the 
text string should contain, whether to treat the number as signed or unsigned, and 
whether to fill leading columns with zeros or spaces. 

A FormatProc is the destination of all output from the format routines. It is the main 
component of an Object. It should pass the characters of r to the appropriate sink and 
update h.context to reflect the context of the last character of r. 

64.1.2 Operations 

There are two major classes of operations in XFormat. The first class is used to format 
various data types and pass them to a format procedure. These operations contain simple 
text operations such as Blanks, Reader, and String; numeric operations such as Decimal 
and Number; network-related operations such as Network Address and HostNumber; and 
some compatibility routines such as NSString. All these operations direct their output to 
the format procedure in their handle parameter. If this parameter is defaulted, it is 
directed to the default output sink. 
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The second class of operations provide built-in format procedures that direct their output to 
the following well-known data types: xstring.Writer, stream. Handle, tty. Handle, and 
NSString.String. 

64.2 Interface Items 

64^1 Handles and Objects 

Handle: TYPE ■ LONG POINTER TO Object; 

Object: type ■ record [ 
proc: FormatProc. 

context: xstn'ng.Context 4-xstrmg.vanillaContext, 
data: ClientData <- nil]; 

FormatProc:TYPE « procedure [r: xstring. Reader, h: Handle]; 

ClientData: TYPE ■ long pointer; 

A Handle is a parameter to all the formatting operations. Its object encapsulates the output 
sink that is the destination of all formatted text. The proc field is called one or more times 
for each formatting operation; it should pass the characters of its reader parameter to the 
output sink it implements. The context field is used to hold the context of the last character 
sent to the format procedure. It should be updated by the format procedure. The data field 
allows client-specific information to be passed to the format procedure. 

64.2.2 Default Output Sink 

SetOefaultOutputSink: procedure [new: Object] returns [old: Object]; 

SetOefaultOutputSink sets the default object that is the default destination for all 
formatted output. For each of the formatting operations, if the handle parameter is nil, it is 
directed to the default output sink. The default output sink is initialized to an object that 
ignores all results. 

64.2.3 Text Operations 

Blanks: procedure [h: Handle NIL, n: cardinal 1]; 

Blanks calls on h.proc with readers that contain a total of n blanks, h.proc may be called 
more than once. 

Block: PROCEDURE [h: Handle <- NIL, block: Environin«nt.Block]; 

Block calls on h.proc with a reader that contains the characters in block. 

Char: procedure [h: Handle <- NIL, char: xstring.Character]; 

Char calls on h.proc with a reader that contains only the character char. 
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CR: PROCEDURE [h: Handle NIU n: cardinal <- 1]; 

CR calls on h.proc with readers that contain a total of n carriage returns (15C). h.proc may 
be called more than once. 

Line: procedure [h: Handle <- NIL, r: xstring.Reader, n: cardinal <~ 1]; 

Line calls on h.proc with r and then readers that contain a total of n carriage returns (ISO. 
h.proc will be called more than once. 

Reader: procedure [h: Handle <- NIL, r: xstring.Reader]; 

Reader calls on h.proc with r. 

ReaderBody: procedure [h: Handle NIL, rb: xstring.Reader]; 

Reader Body calls on h.proc with @rb. 

String: procedure [h: Handle «- NIL, s: long string]; 

String calls on h.proc with readers that contain the characters in s. 

64.2.4 Number Formats 

NumberFormat: TYPE » record (base: [2..36] 10, 

zerofill: boolean false, signed: boolean *- false, columns: [0..255] 0 ]; 

NumberFormat is used by the number-formatting procedures. The number will be 
formatted in base base in a field at least columns wide (zero means "use as many as 
needed"). If zerofill is true, the extra columns are filled with zeros; otherwise, spaces are 
used. If signed is true and the number is less than zero, a minus sign proceeds all output, 
except for columns that are filled with spaces. For bases greater than 10, the characters 
'A..'Z are used as digits. 

NumberFormatX: type > record [base: [2..36] <- 10, 

zerofill: boolean false, signed: boolean false, columns: [0..255] 4-0, 
numberParms: XDigits.NumberParms <-XDigits.defaultNumberParms]; 

NumberFormatX is the same as NumberFormat except that numberParms can be specified. 
If base is other than 10, numberParms.representation and numberParms.thousandsSep 
are ignored. See the XDigits chapter for more details. Fine Point: This type is currently found in 
XFormatX. 

OecimalFormat: NumberFormat a [ 

base: 10, zerofill: false, signed: true, columns: 0]; 

HexFormat: NumberFormat ■ [ 

base: 16, zerofill: false, signed: false, columns: 0]; 

OctalFormat: NumberFormat ■ [ 

base: 8, zerofill: false, signed: false, columns: 0]; 
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UnsignedDecimal Format: NumberFormat ■ [ 

base: 10, zerofiii: false, signed: false, columns: 0]; 

These are useful number format constants. The output will fill as many columns as needed. 

64.2.5 Numeric Operations 

Number: procedure [ 

h: Handle 4- NIL, n: long UNSPEaFiEO, format: NumberFormat]; 

Number formats n to a string according to the number format format. The number will be 
formatted in base base in a field at least columns wide (zero means "use as many as 
needed"). If zerofiii is true, the extra columns are filled with zeros; otherwise, spaces are 
used. If signed is true and the number is less than zero, a minus sign proceeds' all output, 
except for columns that are filled with spaces. For bases greater than 10, the characters 
'A..'Z are used as digits, h.proc will be called several times with pieces of the output as they 
are generated. 

NumberX: procedure [ 

h: Handle 4- Nil., n: long unspecified, format: NumberFormatX]; 

NumberX formats n to a string according to the number format format. NumberX is the 
same as Number except that format is of type NumberFormatX wherein the numberParms 
can be speciHed. See the XDigits chapter for more details. Fine Point: This procedure is'currentiy 

exported through XFormatX. 

Decimal: procedure [h: Handle «- NIL, n: long integer]; 

Decimal converts n to signed base 10. It is equivalent to Numberfh, n, DecimalFormat]. 

DecimalX: procedure [h: Handle <- NIL, n: long integer. 

numberParms: xoigit.NumberParms 4-xoigits.defaultNumberParms]; 

DecimalX converts n to signed base 10. It is equivalent to NumberX[h, n, DecimalFormat]. 
See the XDigits chapter for more details. Fine Point: This procedure is currently exported through 
XFormatX. 

Hex: procedure [h: Handle NIL, n: long cardinal]; 

Hex converts n to signed base 16. It is equivalent to NumberCh, n, HexFormat]. 
Octal: PROCEDURE [h: Handle NIL, n: long UNSPEaFiEo]; 

Octal convert n to base 8. When n is greater than 7, the character 'B is appended. It is 
equivalent to Number[h, n, OctalFormat]; if n > 7 then Charfh, 'B.ord]. 

64.2.6 Built-in Sinks 

The XFormat interface provides several built-in format procedures that know how to send 
output to particular destinations. For each of the four known types of destinations 
(xstring.Writer, stream.Handle, TTY.Handle, and NSString.Strlng), there are both the format 
procedure as well as an operation that returns an object initialized with the appropriate 
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format procedure and destination data. Both the format procedures and the object 
operations may raise the error Error{nilData] if the expected data is nil. 

NSStringProc: FormatProc; 

NSStringObject: procedure [s: long pointer to NSString.Stnng] returns [Object]; 

NSStringProc appends the reader to an NSString.String. It expects h.data to be a long pointer 
TO NSString.String. NSStringObject constructs an object whose proc is NSStringProc and 

whose data is s. 

StreamProc: FormatProc; 

StreamObject: procedure [sH: straam.Handle] returns [Object]; 

StreamProc puts the bytes of the reader to a Stream. Handle. It expects h.data to be a 
Stream.Handle. StreamObject constructs an object whose proc is StreamProc and whose data 
issH. 

TTYProc: FormatProc; 

TTYObject: procedure [h: TTY.Handie] returns [Object]; 

TTYProc puts the bytes of the reader to a TTY.Handie. It expects h.data to be a TTY.Handie. 
TTYObject constructs an object whose proc is TTYProc and whose data is h. 

WriterProc: FormatProc; 

WriterObject: procedure [w: XString.Writer] returns [Object]; 

WriterProc appends the reader to a XString.Writer. It expects h.data to be a xstring.Writer. 
WriterObject constructs an object whose proc is WriterProc and whose data is w. 

64.2.7 Date Operation 

DateFormat: TYPE ■ {dateOnly,timeOnly«dateAndTime}; 

DateFormat allows the user to specify which template from XT! me is used when the date is 
to be formatted by the procedure Date. 

Date: procedure [ 

h: Handle NIL, time: System. GreenwichMeanTime 4~System.gmtEpoch, 
format: DateFormat <- dateAndTime]; 

Date converts time to a string by calling xTime.Append, using format to specify which 
template to use. h.proc is then called. If time is defaulted, the current time is used. 

64.2.8 Network Data Operations 

NetFormat: type ■ {octal, hex, productSoftware}; 
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NetFormat is used by the procedures that format network addresses, octal converts the 
number to octal, hex converts to hex, and productSoftware converts the item to a decimal 
number and then inserts a every three characters, starting from the right. An example 
of a number in product software format is 4-294-967-295. 

HostNumber: procedure [ 

h: Handle <- NIL, hostNumber: Syst«m.HostNumber, format: NetFormat]; 

HostNumber calls on h.proc with a reader that contains hostNumber formatted as defined 
by format. 

NetworkAddress: procedure 

h: Handle 4- NIL, networkAddress: System.NetworkAddress, format: NetFormat]; 

NetworkAddress calls on h.proc with a reader that contains networkAddress with the 
form network'number#host-numberit'socket'number, where the format of the various 
components isdetermined by format. 

NetworkNumber: procedure [ 

h: Handle 4- NIL, networkNumber: System.NetworkNumber, format: NetFormat]; 

NetworkNumber calls on h.proc with a reader that contains networkNumber formatted as 
defined by format. 

SocketNumber: procedure [ 

h: Handle <- NIL, socketNumber: System.SocketNumber, format: NetFormat]; 

SocketNumber calls on h.proc with a reader that contains socketNumber formatted as 
defined by format. 

64.2.9 NSString Operations 

NSChar: procedure [h: Handle 4~ NIL, char: NSString.Character]; 

NSChar calls on h.proc with a reader that contains the character char. 

NSLlne: procedure [h: Handle <- NIL, s: NSString.String, n: cardinal 4-1]; 

NSLine calls on h.proc with a reader that contains the characters in s, then calls on 
readers that contain a total of n carriage returns (15C). h.proc may be called more than 
once. 

NSString: procedure [h: Handle 4- NIL, s: NSString.String]; 

NSString calls on h.proc with a reader that contains the characters in s. 

64.2.10 Errors 

Error: error [code: ErrorCode] ; 
ErrorCode: type » {invalidFormat, nilData}; 
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invaiidFormat The term invalidFormat means an invalid operation has been 
attempted 

nilData The term nilOata means h.data was nil, but the format procedures 

wanted valid data. 



64.3 Usage/Examples 

64.3.1 Using Built-in Sinks 

The XFormat interface allows clients to convert data t3rpes to their textual representation. 
By using the built-in sinks, clients can put this text into streams, tty. handle, and append to 
writers. In particular, although the XString interface does not include any append number 
operations, XFormat may be used to accomplish this task. 

AppendNumber: procedure [ 

w: XString. Writer, n: long integer, format: XFormatNumberFormat] » { 
xfo: XFormat.Object *- XFormat. WriterObject(w]; 
XFormat.Number[h: @xfo, n: n, format: format]}; 

64.3.2 Creating New Format Procedures * 

' While XFormat provides some useful output sinks, clients may wish to build new sinks. 
The following example hypothesizes a log window that can display text in. a window and 
allows appending of text to the end. 

LogWindow: definitions ■ { 

Create: procedure [w: window.Handle, file: NSFUe.Handle]; 
Destroy: procedure [w: window.Handle]; 

LogReader: procedure [w: window.Handle, r: xstring.Reader]; 
Info: PROCEDURE [w: window.Handle] returns [ 

file: NSFiie.Handle, nChars: long integer. endContext: xstring.Context]; 

Log FormatProc : XFormat. FormatProc; 

LogFormatObject: procedure [w: window.Handle] returns [object: XFormat.Object] 

ErrorCode: type ■ {notALogWindow}; 

Error: Error [code: ErrorCode]; 

}.. 

LogWindowlmpI: PROGRAM ■ { 

Create: public procedure [w: window.Handle, file: NSFiie.Handle] ■ {...}; 
Destroy: PUBLIC PROCEDURE [w: Window.Handle] ■ {...}; 

LogReader: public procedure [w: window.Handle, r: xstring.Reader] « {...}; 
Info: public procedure [w: window.Handle] returns [ 

file: NSFiie.Handle, nChars: long integer, endContext: xstring.Context] > {...}; 

LogFormatProc: PUBLIC XFormat.FormatProc « { 
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w: window.Handle > h.data; 

IF w ■ NIL THEN ERROR XFormat.ErrorfnilData]; 

LogReader[w: w, r: r]; 

h.context «- lnfo[w].endContext}; 

LogFormatObject: pubuc procedure [ 
w: Window.Handle] returns [object: XForinat.Object] ■ { 
IF w ■ NIL THEN ERROR XFormat. Error[ni I Data]; 

RETURN([proc: LogFormatProc, context: info(w].endContext, data: w]]}; 

}.. 

The bulk of the work is done in the LogReader procedure. It is assumed that the log window 
keeps track of the context of the end of the log so that it will add the necessary character set 
shift information when a reader that begins with a different character set is logged. If the 
log window didn't take care of this, the format procedure would have to set that itself, as 
the stream format procedure example below shows. 

StreamProc: PUBLIC xFormat.FormatProc ■ { 

stream: straam.Handle » h.data; 
. startsWith377B: boolean; 

c: xstring.Context;* 

IF stream ■ nil then error xFormat.Error[niiData]; 

[context: c, startsWith377B: startsWith377B] ^xstring.Readerlnfo[r]; 

SELECT TRUE FROM 

startsWlth377B » > null; 
csuffixSize a 2 * > 

if h.context-suffixSize « 1 then { 

stream.PutByte[377Bl; stream.PutByte(377Bl; stream. PutByte(01}; 
h.context.suffixSize » 2, cprefix # h.context.prefix » > { 

stream.PutByte[377Bl; stream.PutByte(c.prefix]}; 
endcase; 

stream.PutBiock[biock: xstrtng.Biock[r]]; 
h.context *- xstring.ComputeEndContext(r]}; 



64-8 



Viewpoint Programmer's Manual 



64 



64.4 Index of Interface Items 

Item Page 

Blanks: procedure 2 

Block: PROCEDURE 2 

Char: procedure 2 

ClientData: type 2 

CR: PROCEDURE 3 

Date: procedure 5 

OateFormat: type 5 

Decimal: procedure 4 

DecimaiX: procedure 4 

Decimal Format: NumberFormat 3 

Error: error 6 

ErrorCode: type 6 

FormatProc: type 2 

Handle: type 2 

Hex: procedure 4 

HexFormat: NumberFormat 3 

HostNumber: procedure 6 

Line: PROCEDURE 3 

NetFormat: type 5 

NetworkAddress: procedure 6 

NetworkNumber: PROCEDURE 6 

NSChar: PROCEDURE 6 

NSLine: PROCEDURE 6 

NSString: procedure 6 

NSStringObject: procedure 5 

NSStringProc: FormatProc 5 

Number: procedure 4 

NumberX: procedure 4 

NumberFormat: type 3 

NumberFormatX: type 3 

Object: type 2 

Octal: procedure 4 

OctaiFormat: NumberFormat 3 

Reader: procedure 3 

ReaderBody: procedure 3 

SetOefaultOutputSink: procedure 2 

SocketNumber: procedure 6 

StreamObject: procedure 5 

StreamProc: FormatProc 5 

String: procedure 3 

TTYObject: procedure 5 

TTYProc: FormatProc 5 

UnsignedDecimalFormat: NumberFormat 4 

WriterObject: procedure 5 

WriterProc: FormatProc 5 
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65.1 Overview 

XLReai is a decimal real package that supports manipulation of real numbers with greater 
precision than Mesa reals. 

65.2 Interface Items 

65.2.1 Representation 

Numbers are maintained as 13 decimal digits of signed mantissa with a 10-bit exponent 
(-512 to 511). All routines maintain the normalized numbers, i.e., the first digit is non- 
zero. The assumed decimal point is after the first digit. Numbers are stored as opaque 
objects occupying 4 words (64 bits). 

Digit: type » [0..9]; 
Number: type [4]; 

Bits: TYPE M ARRAY [0..4) OF CARDINAL; 

ValidExponent: type » [-512..511]; 

Digits: type « packed array [0..accuracy) of Digit; 

accuracy: natural « 13; 

65.2.2 Conversion 

XLReai provides routines to convert numbers to and from other representations such as 
LONG INTEGERS and REALS as well as routines to look at pieces of numbers. 

NumberToPaIr: procedure [ 

n: Number, digits: [1 ..accuracy]] returns [negative: boolean, exp: integer, mantissa: 
Digits]; 

PairToNumber: procedure! 

negative: boolean, exp:iNTEGER, mantissa: Digits] returns [n: Number]; 
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In PairToNumber and NumberToPair, the decimal point, is between mantissaCO] and ^tln^ 
mantissa[l]. NumberToPair rounds n so that mantissa contains digits significant digits. All 1 
other digits are zero. NumberToPair may raise Error[notANumber]. PairToNumber may 
raise Error[underflow]. 

IntegerPart, FractionPart: procedure [Number] returns [Number]; 

IntegerPart and FractionPart may raise Error[notANumber]. FractionPart may also raise 
Error[overflow]. 

Fix:PR0CE0URE [Number] returns [long integer]; 
Float: procedure [long integer] returns [Number]; 

Fix may raise Error[notANumber] and Error(overflow]. Fix rounds (as, opposed to truncate). 
ToREAL:procedure [number: Number] returns [real]; 

ToREAL converts number to a real. If Abs[number] is greater than the largest real 
(3.40282347E38) it will return Reai.Plusinfinity or Real.Minusinfinity depending on 
number's sign. If it less than the smallest real (1.17549435E-38) it will return 
ReaLPtusZero or Real.MinusZero depending on number's sign. Some precision may be lost 
since a number's precision is greater than a real's precision. ToREAL may raise 
Error[nOtANumber]. Fine Point: This procedure is currently exported through XLRealX. 

FromREAL: procedure [real: real] RETURNS [Number]; ^\ 

FromREAL converts real to a Number. If real is Reai.Plusinfinity or Real.Minusinfinity, 
FromREAL returns 9.999999999999E511 or -9.999999999999E511 depending on real's 
sign. If real is not a number, FromREAL returns MakeSpecial[0];. Fine Point: This procedure is 
currently exported through XLRealX. . 

65.2.3 Input/Output 

The input and output routines convert numbers to and from a stream of characters. 
ReaderToNumber: PROCEDURE[r: xstring.Reader] returns [Number]; 

ReaderToNumber converts r into a number. The number may have leading and trailing 
white space (spaces, tabs and returns). It may raise Errorloverflow] if the number is too big 
or Error[notANumber] If the reader contains invalid characters. 

ReaderToNumberX: procedure[ 
r: xstring.Reader, 

numberParms: XDigits.NumberParms <-xoigits.defaultNumberParms, 
decimalSep: xchar.Character <-xchar.not] returns [Number]; 

ReaderToNumberX is the same as ReaderToNumber except that the numberParms and 
decimalSep can be specified. If decimalSep is defaulted then the decimal separator 
described in the XComSoft messages file is used. See the xoigits chapter for more 
information. Fine Point: This procedure is currently exported through XLRealX2. 
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ReadNumber: procedure [ 

get: proc returns [xchar.Character], putback: proc [xchar.Character]] returns [Number]; 

ReadNumber converts the stream of characters from get into a number. Any character 
other than white space, ' + , 'E, 'e, •0-*9, or the decimal separator will cause conversion to 
terminate and putback will be called with that character. It may raise Error[overf low]. 

ReadNumberX: procedure [ 

get: proc returns [xchar.Character], 
putback: proc [xchar.Character], 

numberParms: XDigits.NumberParms ^XDigits.defaultNumberParms, 
decimalSep: xchar.Character 4-xchar.not] returns [Number]; 

ReadNumberX is the same as ReadNumber except that the numberParms and decimaiSep 
can be specified. If decimaiSep is defaulted then the decimal separator described in the 
XComSoft messages file is used. See the XDigits chapter for more information. Fine Point: This 
procedure is currently exported through XLRealX2. 

FormatReai: procedure [h: XFormat.Handle NIL, r: Number, width: natural]; 

FormatReai formats r into a field width elements wide and passes the resulting text to h. If 
the number does not fit the field is ^Ued with *> characters, h.proc may be called more 
than once. 

PictureReai: procedure [ 

h: XFormat-Handle NIL, r: Number, template: xstring. Reader]; 

PictureReai is not implemented. Use FormatNumber for control over output. 

NumberFormat: type > record [ 
columns: ColumnCount <- 0, 
type: FormatType <- fixed, 
fill: Fill 4- [none, 0], 

digitSpec: select choice: OigitChoice from 
fractions « > [fractions: DigitCount], 
digits ■ > [digits: DigitCount], 
ENDCASE4-digits[0]]; 

ColumnCount: type ■ [0..256); 

FormatType: type ■ {fixed, scientific, automatic}; 

Fill: type m RECORD [type: FiilType, nChars: ColumnCount]; 

FillType: type ■ {zero, blank, none}; 

DigitCount: type > [0..accuracy]; 

DigitChoice: type « {fractions, digits}; 

NumberFormat is used by FormatNumber to allow precise control over the formatted 
number, columns specifies the number of columns required; zero means use as many as 
needed, type specifies whether the number is formated in fixed notation (fixed), scientific 
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notation (scientific) or fixed if it will fit in the number of columns or scientific otherwise 
(automatic), fill specifies the type and number of characters of additional fill that is 
required before the number, zero and blank mean use zeros or blanks, respectively, as the 
fill characters, while none means use not fill. digitSpec allows the number of digits or 
fractions to be specified. fractions[n] means have n digits to the right of the decimal. 
digits[n] means have n significant digits in the number, except that digits[0] means have 
any number of digits in the number. 

If type ■ automatic and columns ■ 0, then f.digits is used to determine whether the number 
will be fixed or scientific. This allows a client to say "I want f.digits of significant digits 
and you figure out whether it should be fixed or scientific." Using type ■ automatic and 
columns#0 means that FormatNumber will use columns to determine whether the number 
is fixed or scientific, but often the client wants to specify significant digits rather than 
number of columns, especially since the number of columns will vary depending on the 
format and the value of the number. 

FormatNumber: PR0C[ 

h: XForinat.Handle <- nil, r: Number, 

format: NumberFormat ^ defaultFormat, signallfWontFit: boolean false]; 

defaultFormat: NumberFormat « [ 

columns: 0, type: fixed, fill: [none, OL digitSpec: digits[0]]; . 

WontFit: SIGNAL; 

FormatNumber formats r according to format. If format specifies a number of columns, and 
the formatted number will not fit and signallfWontFit is true, the signal WontFit will be 
raised, If it is resumed or the number won't fit and signallfWontFit is false, 
format.coiumns *> will be passed to h.proc. If the number of columns or digit specification 
restricts the number of significant digits presented, the number of significant digits is 
reduced by rounding. If h is defaulted, output goes to the default output sink. (See the 
XFormat chapter for more details.) The default format specifies fixed notation in as many 
colunms as necessary with no additional fill. If r is negative, the negative sign appears 
before zero fill and after blank fill, h.proc may be called more than once. Fine Point: This 
procedure is currently exported through XLRealX. 

FormatNumberX: proc[ 

h: XFormat.Handle 4- NIL, r: Number, 

format: NumberFormat ^ defaultFormat, signallfWontFit: boolean «- false, 
numberParms: xoigits-NumberParms <- xoigits.defaultNumberParms, 
decimaiSep: xchar.Character4-xchar.not]; 

FormatNumberX is the same as FormatNumber except that the numberParms and 
decimaiSep can be specified. If decimaiSep is defaulted then the decimal separator 
described in the XComSoft messages file is used. See the xoigits chapter for more details. 
Fine Point: This procedure is currently exported through XLRealX2. 

65.2.4 Comparison 

Comparison: type » {less, equal, greater}; 
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Compare: procedure [a, b: Number] returns [Comparison]; 

Less, LessEq, Equal, GreaterEq, Greater, NotEq: procedure [ 
a, b: Number] returns [boolean]; 

Any of tlie compare operations may raise ErrorCnotANumber]. 

65.2.5 Operations 

Add, Subtract, Multiply, Divide, Remainder: procedure [ 
a, b: Number]RETURNS [Number]; 

Add, Multiply, Divide and Remainder may raise Error[notANumber] and Error[overflow] 
Divide may also raise Error[divideByZero]. 

Exp: procedure [Number] returns [Number]; 

Exp computes the results by continued fractions. Exp may raise Error[underflow], 
Error[notANumber] and Error[overfiow]. 

Log: PROCEDURE [base, arg: Number] RETURNS [Number]; 

Log computes the logarithm to the base base of arg by Ln(arg)/Ln(base). Log may raise 
Error[overflow], Error[invaiidOperation], and Error[notANumber]. 

Ln: PROCEDURE [Number] returns [Number]; 

Ln may raise Error[notANumber] , Error[overflow] , and Error[lnvalidOperation]. 
Power: procedure [base, exponent: Number] returns [Number]; 

Power calculates base to the exponent power by e(exponent*Ln(base)). Power may raise 
Error[notANumber] and Error[overfiow]. 

Root: PROCEDURE [index, arg: Number] returns [Number];- 

Root calculates the index root of arg by e(Ln(arg)/index). Root may raise Error[overflow], 
Error[notANumber], and Error[underflow]. 

SqRt: PROCEDURE [Number] returns [Number]; 

SqRt calculates the square root of the input value by Newton's iteration. SqRt may raise 
Error[notANumber] and Error[invalidOperation]. 

Abs, Negative, Double, Half: procedure [Number] returns [Number]; 

Abs, Negative, Double and Half may raise Error[notANumber] Double may also raise 
Error[overflow]. 

Cos: PROCEDURE [radlans: Number] returns [cos: Number]; 
Sin: procedure [radians: Number] returns [sin: Number]; 
Tan: procedure [radians: Number] returns [tan: Number]; 
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Computes the trigonometric function by polynomial. Angles are measured in radians 
measured counterclockwise from the positive x axis about the origin [0, 0]. Sin, Cos and 
Tan may raise Error[notANumber] and Error[invaiidOperation] (if radians.exponent>ll). 
Tan may also raise Error[overfiowI. 

ArcCos PROCEDURE [x: Number] returns [radians: Number]; 
ArcSin procedure [x: Number] returns [radians: Number]; 
ArcTan procedure [x: Number] returns [radians: Number]; 

Transcendental functions have an accuracy of about 1X10,'^^. ArcCos, ArcSin and ArcTan 
may raise Error[notANumber]. ArcSin may also raise Error[invaiidOperation] (if x NOT IN 
[-1..1]). 

65.2.6 Special Numbers 

A client can create special numbers that will cause the Error[notANumber] to be raised if 
used in any arithmetic operation. 

Speciailndex: type » natural; 

MaiceSpeclai: procedure [index: Speciailndex] returns [Number]; 
IsSpecial: procedure [Number] returns [yes: boolean, index: Speciailndex]; 

65.2.7 Errors 

Error: error [code: ErrorCode]; 

ErrorCode: type » {bug, divideByZero, invalidOperation, notANumber, overflow, 
underflow, unimpiemented}; 

notANumber means the number passed in is a special number. 

65.2.8 Special Constants 

zero: Number ■ loophole[ Bits[0, 0, 0] ]; 

Pi: procedure returns [Number]; 
E: PROCEDURE RETURNS [Number]; 

65.3 Usage/Examples 

65.3.1 Special Numbers 

"Make the special number 

special :xLReai.Number XLReaLMai(eSpecial[1]; 

"do some computations w/'t/i Numbers 

"If a problem occurs during computation, assign 
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n4- special 
[] 4~XLReai.Ln[n]; 

"ifn 3 special this call to XLReal.Ln will raise Error[notANumber] 

65.3.2 Times of Common Operations 

For the four arithmetic operations, typical timings (in microseconds) compared with the 
current Common Software 32-bit IEEE floating-point package (with no microcode assist) 
are: 





XLReal 


REAL 


Add or Subtract 


500 


800 


Multiply 


800 


1000 


Divide 


1500 


1900 
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65.4 Index of Interface Items ,1^1^ 

Item Page Item Page 

Abs:pROCEOURE 5 Greater:PROCEDURE S 

accuracy:coNSTANT 1 HalfiPROCEOURE 5 

AcIcI:proceoure 5 lntegerPart:pROCEOURE 2 

ArcCos: PROCEDURE 6 IsSpecial: PROCEDURE 6 

ArcSin:pROCEOURE 6 Less.'PROCEOURE 5 

ArcTan:pROCEOURE 6 LessEq:pROCEDURE 5 

Bits: TYPE 1 Ln:pROCEDURE 5 

ColumnCount:TYPE 3 LogiPROCEOURE 5 

CompareiPROCEOURE 5 MakeSpecial: procedure 6 

Comparison :type 5 iy^uttiply:PROCEDURE 5 

Cos:proceoure 6 Negative:pROCEOURE 5 

defaultFormat:cONSTANT 4 NotEq: procedure 5 

Digit: TYPE 1 Number: type 1 

DigitChoice:TYPE 3 NumberFormat: type. 3 

DigitCountiTYPE 3 NumberToPair:PROCEDURE 1 

Digits:TYPE 1 PairToNumber:PROCEOURE 1 

Divide:pROCEDURE 5 Picproceoure 6 

Doubie:PROCEDURE 5 PictureReal: procedure 3 

E:procedure 6 Power: procedure 5 

Equal: PROCEDURE 5 ReaderToNumber: procedure 2 

Error: ERROR 6 ReaderToNumberX:PROCEOURE 2 

ErrorCode:TYPE 6 ReadNumber:PROCEOURE 3 

ExpiPROCEOURE 5 ReadNumberXiPROCEOURE 3 

Fill:TYPE 3 Remainder: PROCEDURE 5 

FillTypeiTYPE 3 Root: procedure 5 

Fix:pROCEOURE 2 Sin:pROCEDURE 6 

Float:pROCEDURE 2 Speciallndex: TYPE 6 

FormatNumber: PROCEDURE 4 SqRt:PROCEOURE 5 

FormatNumberX:PROCEDURE 4 Subtract:PROCEDURE 5 

FormatReal: PROCEDURE 3 Tan:PROCEDURE 6 

FormatType:TYPE 3 ToREAL: procedure 2 

FractionPart: PROCEDURE 2 ValidExponent:TYPE 1 

FromREAL:PROCEDURE 2 WontFit: signal 4 

GreaterEq:PROCEDURE 5 zero:C0NSTANT 6 
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66.1 Overview 



The XMessage interface supports the multilingual requirements of systems requiring that 
the text to be displayed to the user be separable from the code and algorithms that utilize 
it. This allows workstation applications to define messages and developers and translators 
to supply the international representations of the text. The XMessage interface defines the 
message transfer mechanism necessary for applications to define application-specific 
messages, register them with the system, and access them. 

The XMessage interface is part of the entire message machinery that provides 
multilingual text. Applications must be written to rely on messages for their text. A tool 
translates messages and produces a file containing the translated version of the messages. 



66.1.1 Message Usage 

Applications define collection of messages and refer to them by using a Handle. A unique 
key relative to that handle represents each message. To get the text of a message, the 
client calls Get or GetList. During development of applications, message handles are 
obtained by calling AilocateMessages and RegisterMessages. When the development is 
completed and a message file is generated, message handles are obtained by calling 
MessagesFromFile or MessagesFromReference. 

Applications should be broken into three parts: the main code of the application that uses 
the messages, the code that defines and initializes the messages, and the code that gets 
message handles from the message file. 

66.1.2 Message Composition and Templates 

Frequently, text presented to the user should include items like names and sizes of objects, 
dates,and so forth. When defining such messages, it is best to define a single message 
template that allows certain fields to be filled in with this information. The piecemeal 
approach to constructing a understandable sentence normally does not work when the 
message is translated to a different language. 
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Templates are messages that will have additional text merged into them. The fields in 
templates are deHned by numbers enclosed in angle brackets if the template contains 
multiple fields, or simply by angle brackets, if there is only one field. 



Handle: TYPE ■ long pointer to Object; 
Object: type; 

A Handle represents a collection of messages. It is normally associated with a particular 
application. It is obtained from the AllocateMessages operation and is a parameter of most 
operations. 



Get: PROCEDURE [h: Handle, msgKey: MsgKey] returns [msg: xstring.ReaderBody]; 

Get returns the message corresponding to the given message key within the group of 
messages specified by h. 

GetLlst: procedure [h: Handle, msgKeys: MsgKeyList, msgs: StringArray]; 
MsgKeyUst: type * long descriptor for array of MsgKey; 
StringArray: type * long descriptor for array of xstring.ReaderBody; 

GetList fills the array of reader bodies with the bodies of the messages whose keys are in 
the message key list. This procedure is equivalent to: 

FOR I IN [0..msgKeys.LENGTH) do msgs[i] Get(msgKeys[i]]; endloop. 

This procedure raises Error[lnvalidMsgKeyList] if msgKeys is nil, Error[invalidStringArray] 
if msgs is nil, and Error[arrayMlsmatch] if the lengths of the two descriptors are not equal. 



ComposeToFormatHandle: procedure [ 

source: xstring.Reader, destination: XFormat.Handle, args: StringArray]; 

Compose: procedure [ 

source: xstring.Reader, destination: xstring. Writer, args: StringArray]; 

ComposeToFormatHandle and Compose compose a message by replacing the fields in 
source with the text in args. ComposeToFormatHandle uses an XFormat.Handle as the 
destination of the message, while Compose uses an xstring.Writer. A field is specified by a iiiiliii^ 
number enclosed in angle brackets. These operations may raise Error[invalidString] if ^ 
source is empty and Error[notEnoughArguments] if args is nil. To maintain backward 




66.2 Interface Items 



66.2.1 Handles 



66.2.2 Getting Messages 



66.2.3 Composing Messages 
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compatibility with existing messages, the string array is one origin (that is, the field < 1 > 
accesses args[0]; 

ComposeOneToFormatHandie: procedure [ 

source: xstring.Reader, destination: XFormatHandie, arg: xstring.Reader]; 

ComposeOne: procedure [ 

source: xstring.Reader, destination: xstring.Writer. arg: xstring.Reader]; 

ComposeOneToFormatHandie and ComposeOne compose a message by replacing the 
single field in source with arg. ComposeOneToFormatHandie uses an XFormat.Handle as 
the destination of the message, while ComposeOne uses an xstring.Writer. The single field 
is specified by empty angle brackets, < >. These operations may raise Error[invaiidString] 
if source is empty and Error[notEnoughArguments] if arg is nil. 

Decompose: procedure [source: xstrjng.ReaderI returns [args: StringArray]; 

Decompose currently does nothing. 

66.2.4 Defining Messages 

Messages are defined by constructing an array of message entries and registering them 
with the system. 

Messages: type ■ long descriptor for array of MsgEntry; 

MsgEntry: TYPE ■ record! 
msgKey: IVIsgKey, 
msg: xstrmg.ReaderBody, 
transiationNote: long string nil, 
translatable: boolean true, 
type: MsgType «- userMsg, 
Id: MsglO]; 

MsgKey: type « cardinal: 

MsgType: type > {userMsg, template, argList, menuitem, pSheetltem, commandltem, 
errorMsg, infoMsg, promptltem, windowMenuCommandr others}; 

MsglD: type a cardinal; 

Messages describes a group of message entries and is a parameter to RegisterMessages. A 
MsgEntry contains information about each message. The msgKey field is the Handle- 
relative key of the message. The msg field contains the text of the message itself, while all 
other fields are to help in the translation process. The tranlationNote field provides notes 
to the translator. The translatable boolean indicates whether the message should be 
translated. The MsgType enumerated provides a hint of how the message will be used. The 
MsglO is a unique identifier for the message. For a given group of messages, each message 
should have a unique value for its MsglD. The MsglD must remain unique for all time, 
across all releases. This ID allows the translators to determine when a new message has 
been added or an old message deleted. 
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AliocateMessages: procedure [ 

appiicationName: long string, maxMsgindex: cardinal, 
ciientData: ClientData, proc: DestroyMsgsProc] 
RETURNS [h: Handle]; 

CiientData: type « long pointer; 

DestroyMsgsProc: type « procedure [ciientData: CiientData]; 

AliocateMessages allows a client to define a domain of messages for subsequent registry 
and access. All access to messages will be relative to the returned handle. The 
appiicationName parameter names the message domain to the message implementation. 
maxMsgindex defines the maximum number of messages that are registered for this 
domain. The CiientData and DestroyMsgsProc parameters are provided to notify the client 
when the DestroyMessages operation is invoked. 

RegisterMessages: procedure [ 

h: Handle, messages: Messages, stringBodiesAreReal: boolean]; 

RegisterMessages allows a client to initialize a domain of messages. It uses the 
StringBodiesAreReal boolean to decide whether to copy the byte sequences of the messages. 
If StringBodiesAreReal is false, it copies the reader body and bytes of the messages field in 
each entry of messages. If it is true, RegisterMessages copies the reader body of the entry 
and relies on the bytes to not be deallocated until after a call to DestroyMessages. 

66.2.6 Obtaining Messages from a File 

MessagesFromFlie: procedure [ 
fileName: long string, ciientData: CiientData, proc: DestroyMsgsProc] 
RETURNS [msgDomains: MsgDomains]; 

MessagesFromReference: procedure [ 
file: NSFiie.Reference, ciientData: CiientData, proc: DestroyMsgsProc] 
RETURNS [misgDomains: MsgDomains]; 

MsgDomains: TYPE ■ long descriptor for array of MsgDomain; 

MsgDomain: type « record [ 

appiicationName: xstring.ReaderBody, 
handle: Handle]; 

MessagesFromFile and MessagesFromReference return a sequence of message domains 
that are name, message handle pairs. MessagesFromFile gets the messages from the file 
named fileName in the system folder, while MessagesFromReference gets the messages 
from the file whose reference is file. Storage for msgDomains must by freed by calling 
FreeMsgDomainStorage. The CiientData and DestroyMsgsProc parameters are provided 
to notify the application when the DestroyMessages operation is invoked. 
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FreeMsgDomainsStorage: procedure [msgDomains: MsgOomains]; 

66.2.7 Destroying Message Handles 

OestroyMessages: procedure [h: Handle]; 

DestroyMessages invokes the OestroyMsgsProc associated with the handle and then frees 
any resources that are currently associated with h. The handle should no longer be used. 

66.2.6 Error 

Error: error (type: ErrorType]; 

ErrorType: type * { 
arrayMismatch, invalidArgindex, invalidMsgKey, invaiidMsgKeyList, 
invandStringArray, invalidString, notEnoughArgume'nts}; 

66.3 Usage/Examples 

66.3.1 Structuring Applications to Use Messages 

Applications that use messages have at least two parts. The first part is the code for the 
application's functions. It is produced by programming tools such as the compiler and 
binder with Mesa source programs as Input. The second part consists of the messages that 
provide text to the user. The application defines its messages and provides initial 
information to the translators of the messages. 

Messages that are to be translated must be able to communicate in a precise type-safe way. 
Throughout the translation process, it should be possible to verify the message with its 
original version. 

The cleanest and safest possible interface between application developers (message 
de^uiers) and translators is to deliver a bed that Contains all the messages used by the 
appliciation as well as a well-defined mechanism for communicating them to some client. 
The RegisterMessages procedure provides the mechanism; all else that is needed is to 
avoid other distractions (like importing or exporting of application private facilities). To 
that end, the following conventions are proposed for modules/configurations that define 
and register messages: 

1. Isolate message definition code into modules whose sole function is to define and 
register the message text for the application. 

2. Allocate the Handle and register all messages via the modules' configuration's start 
code. 

3. If multiple modules are required to define the application messages, provide a 
configuration that starts all modules in the the correct order and provides the correct 

IMPORTS and EXPORTS. 

4. XMessage definition modules and configurations must not depend upon application- 
specific facilities. The imports list of any message-defining module should be restricted 



66-5 



66 XMessage 



to procedures defined in the XMessage interface (such as RegisterMessages, ^^^^ 
AllocateMessages,and so forth). ^' 

As a consequence of 2 and 4 above, applications must provide a mechanism for 
communicating the Handle between suppliers of messages (callers of ResisterMessages) 
and users of messages (callers of GetMsg, and and so forth) . A simple solution is to have 
the message-definition module export a procedure that returns the handle. 

66.3.2 Example of Message Usage 

The following message example has three segments. The first is an interface that defines 
the messages for the example. The second is the module that provides the raw material for 
the messages. This module is used to supply the message text while running the 
application while it is being developed. It is used to supply the raw data to the message 
translators. The third part is the module that uses the messages. 

— ExampleMessage.mesa 

DIRECTORY 

XMessage using [Handle]; 
ExampieMessage: definitions a begin 

Keys: TYPE s MACHINE DEPENDENT { 

delete(0),confirniOelete(1),deieteOone(3)...}; 
GetHandle: procedure RETURNS[h: XMessage.Handle]; 
END. ~ of ExampieMessage: 



" ExampleMessagelmpLmesa 

DIRECTORY ... 

ExampleMessagelmpI: program 
imports ... 

EXPORTS ExampieMessage ■ begin 
h: XMessage.Handle; 

GetHandle: PUBUC procedure returns [xMessage-Handle] « {returnIH]}; 

DeieteMessages: XMessag«.OestroyMsgsProc ■ {}; 

Init: procedure » ( 

msgArray: array Keys of XMessagcMsg Entry 4- [ 
delete: [ 

msgKey: Keys.delete.ORD, 
msg:xstring.FromSTRING("De!ete"L], 
translationNote: "Delete command name"U 
translatable: true, 
type: menultem, 
id: OL 
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confirmDeiete: [ 

msgKey: Keys.confirmOelete.ORO, 

msg: xstHng.FromSTRINGC'Are you sure you want to delete that item"L], 
translatable: true. 
type: userMsg, 
id: 1L 
deieteOone: [ 

msgKey: Keys.deieteDone.ORO, 

msg: xstring.FromSTRINGCThe item <1 > iias been deleted^L], 
translatable: true, 
type: template, 
id: 311; 

h <- XM«ssag«JVllocateMessages[ 

"Example^U Keys.LAST.0R0.succ. nil, OeleteMessages]; 
XM«ssag«.RegisterMessages[h,LOOPHOLE[LONG[oESCRiPTOR[msgArray]]],FALSE]}; 

InitO; 

END. — of ExampleMessagelmpI 
— ExamplelmpLmesa 

DIRECTORY ... 

ExamplelmpI: PROGRAM 

IMPORTS XMessage, ExampleiMessage > begin 

h: XMessage.Handle « ExampleMessage.GetHandleQ 

OeleteOne: procedure [...]«{ 

r: XString.Reader ■ XMessage.Get(il,ExampieMessage.KeyS.COnfirmOelete.ORD]; 

'}]' 

}. " of ExamplelmpI 
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66,4 Interface Item Index 



Item Page 

AllocateMessages: procedure 4 

ClientData:TYPE 4 

Compose: procedure 2 

ComposeOne: procedure 3 

ComposeOneToFormatHandle:PROCEDURE 3 

ComposeToFormatHandle: procedure 2 

Decompose: procedure 3 

OestroyMessages:PROCEDURE 5 

OestroyMsgsProc: type 4 

Error: error 5 

ErrorType: type 5 

FreeMsgOomai nsStorage : procedure 5 

Get: procedure 2 

GetList: procedure 2 

Handle: type 2 

Messages: type 3 

MessagesFromFile: procedure 4 

MessagesFromReference: procedure 4 

MsgOomain:TYPE 4 

MsgDomains:TYPE 4 

MsgEntry: type 3 

MsgiDtTYPE 3 

MsgKey: type 3 

MsgKeyList: type 2 

MsgType: type 3 

Object: type 2 

RegisterMessages: procedure 4 

StringArray: type 2 
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6T.1 Overview 

The XString interface is part of a string package that supports the Xerox Character 
Standard. It provides the basic data structures for representing encoded sequences of 
characters and some operations on these data structures. 

67.1.1 Character Standard 

The Xerox Character Code Standard defines a large number of characters, encompassing 
not only familiar ASCII characters but Japanese and Chinese Kanji characters and other 
characters to provide a comprehensive character set able to handle international 
information-processing requirements. Because of the large number of characters, the data 
structures in XString are more complicated than a long string's simple array of ASCII 
characters, but the operations provided are more comprehensive*. 

Characters are 16-bit quantities that are composed of two 8-bit quantities: their character 
set and character code within a character set. The Character Standard defines how 
characters may be encoded^ either as runs of 8-bit character codes of the character set or as 
16-bit characters where the character set and character code ai*e in consecutive bytes. See 
the XChar chapter for information and operations on characters. 

67.1.2 Data Structures 

Three main data structures are defined by XString: Context, ReaderBody and WriterBody. 
Contexts provide information for determining how characters are encoded. Reader bodies 
and readers describe a sequence of readonly characters. Writer bodies and writers describe 
a sequence of writeable characters. 

A Context contains information about how characters are encoded in the byte sequence. 
The suffixSize field describes whether the first byte is encoded as an 8-bit character or a 16- 
bit character, the prefix field contains the character set of the first character if the 
encoding is 8-bit characters, and the homogeneous field is true only if there are no 
character set shifts in the sequence of characters. 

A ReaderBody describes some readonly characters that are stored as a sequence of bytes. 
The reader body contains a pointer to the allocation unit containing the bytes, bytes, the 
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offset from the pointer to the first byte, offset, the offset from the pointer of the byte after 
the last byte in the byte sequence, limit, and the context information describing how the ^ 
first character is encoded, context. Most clients should not have to access fields of a reader 
body. Many operations take a Reader, a pointer to a reader body, as a parameter to reduce 
the number of words of parameters. 

A WrIterBody describes some characters that may be edited. In addition to containing all 
the information in a reader body, it also contains an offset from the pointer to the first 
character not in the allocation unit, maxLlmit, the context that describes how the last 
character is encoded, endContext, and the zone that contains the allocation unit, zone. 
Writer bodies are typically passed by reference. 

The designers of XString felt there is a fundamental difference between a string that will 
only be read and one that will be constructed. They felt that the major usage of strings was 
to describe and examine existing strings, not construct new ones. This difference is 
reflected in the two types, readers and writers. 

67.1.3 Operations 

There are a wide range of operations on both readers and writers. Some operations that 
return simple information aiaout readers, such as ByteLength and Empty. Others access 
characters in a reader, such as First, NthCharacter, and Lop. The operation 
ReaderFromWriter can be used to convert a writer to a reader. 

There are operations that create reader bodies from other data structures, such as f^*% 
FromSTRING. Similarily, there are operations that create writer bodies from other 
structures, such as WriterBody FromSTRING. 

Routines allocate and deallocate byte sequences of both readers and writers. 
CopyToNewReaderBody makes a copy of the characters of a reader. NewWriterBody will 
create an empty writer body that can hold a given number of bytes. 
CopyToNewWriterBody is similar to NewWriterBody but initializes the writer with a 
given reader. 

Other operations compare the characters in readers: Equal checks for equality and 
Compare does a multinational lexical comparison. There are operations for scanning 
readers for specific characters. The operation ReaderToNumber converts a reader to a 
numeric value. There are Courier description routines for both readers and reader bodies. 
There is also support for backward-accessing characters in a reader. 

Routines are provided for appending to writers and editing writers. AppendReader 
appends the characters of a reader to a writer. RepiacePiece provides a general editing 
operation for writers. Only the basic appending primitives are provided in XString. The 
XFormat interface can be used to append converted values, such as numbers, to writers. 

67.2 Interface Items 



67.2.1 Contexts 



Context: TYPE > machine dependent record [ 
suffixSize(0:0..6): [1..2], 
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homogeneous(0:7..7): boolean, 
prefix(0:8..15): Byte]; 

A Context contains information about how characters are encoded in the byte sequence. 
The suffixSize field describes whether the first byte is encoded as an 8-bit character or a 
16-bit character, the prefix field contains the character set of the first character if the 
encoding is 8-bit characters* and the homogeneous field is true only if there are no 
character set shifts in the sequence of characters. 

The Character Set Standard describes how characters may be encoded as a sequence of 
bytes. They call the 8-bit character encoding stringlet8 and call the 16-bit character 
encoding stringletl6. In 8-bit character encoding, consecutive bytes contain character 
codes of characters in the same character set. In 16-bit character encoding, the character 
set and character code are contained in consecutive bytes. The suffixSize field describes 
how the characters are encoded; it is 1 for 8-bit character encoding and 2 for 16-bit 
character encoding. 

The prefix field contains the character set of the first character if it is an 8-bit encoded 
character. Subsequent characters in the string use this same prefix unless a character set 
or encoding transition is encountered. It is not used for 16-bit encoded characters. 

The homogeneous field is an accelerator. If it is true, some operations may be faster. It is 
important to set it TRUE only if the byte sequence contains no character set shifts. It is 
alwasrs safe to set it to FALSE. 

emptyContext: Context ■ [suffixSize: 1, homogeneous: true, prefix: 0]; 

vaniilaContext: Context ■ [suffixSize: 1, homogeneous: false, prefix: 0]; 

unknownContext: Context ■ [suffixSize: 1, homogeneous: false, prefix: 377B]; 

emptyContext, vaniilaContext, and unknownContext are three Context constants. An 
empty writer should have emptyContext as its context and endContext. vaniilaContext is 
the default context. unknownContext signiHes that the context is unknown. It is generally 
used only for an end context, a context that describes the last character of a sequence. 

67.2.2 Readers and ReaderBodies 

Reader: TYPE ■ long pointer to ReaderBody; 

ReaderBody: type ■ private machine dependent record [ 
context(O): Context, 
iimit(1): cardinal, 
offset(2): cardinal, 
bytes(3): ReadOnlyBytes]; 

ReadOnlyBytes: type ■ long pointer to readonly ByteSequence; 

ByteSequence: type ■ record! 

packed sequence computed cardinal of Byte]; 
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Byte: type ■ Environment.Byte; 

A ReaderBody describes some readonly characters that are stored as a sequence of bytes. 
The reader body contains a pointer to the allocation unit containing the bytes, bytes, the 
offset from the pointer to the first byte, offset, the offset from the pointer of the byte after 
the last byte in the byte sequence, limit, and the context information describing how the 
first character is encoded, context. Most clients should not have to access fields of a reader 
body. Reader bodies can be thought of as fat pointers. Many operations take a Reader, a 
pointer to a reader body, as a parameter to reduce the number of words of parameters. 

A ReaderBody is like a substring descriptor. The offset and limit Gelds can be changed to 
describe a subsequence of bytes. Routines such as Lop and ScanForCharacter take 
advantage of this substring-like behavior. 

nuilReaderBody: ReaderBody ■ [ 

limit: 0, offset: 0, bytes: nil, context: vanillaContext]; 

nuilReaderBody defines a null value for a reader body. To test for an empty reader body, it 
should no^be compared to nuilReaderBody. The operation Empty should be used instead. 

67.2.3 Writers and Writer Bodies 

Writer: TYPE « long pointer to WriterBody; 

WriterBody : type ■ private machine dependent record [ 
context(0): Context, 
limit(1): cardinal, 
offset(2): cardinal, 
bytes(3): Bytes, 
maxLimit(5): cardinal, 
endContext(6): Context, 
zone(7): uncounted zone]; 

Bytes: TYPE ■ long pointer TO ByteSequence; 

Writers describe a sequence of bytes that may be changed. Writers are bit- wise compatible 
with a reader and contain additional information for storage management and appending 
characters. The maxLimit field describes the limits of the allocation unit, the zone field is 
the zone used for allocating and freeing the bytes, and the endContext field is an 
accelerator for operations that append characters. 

By including a zone in the writer body, operations that add characters to the writer are 
able to allocate a larger byte sequence, copy the old bytes, and update the byte pointer in 
the writer body without invalidating the writer variable that the caller owns. 

nullWriterBody: WriterBody a [ 

limit: 0, offset: 0, bytes: nil, context: vanillaContext, maxLimit: 0, 
endContext: vanillaContext, zone: nil]; 

nullWriterBody defines a null value for a writer body. 
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67.2.4 Simple Reader Operations 

ByteLength: procedure [r: Reader] returns [cardinal] ■ inune 
ByteLength returns the number of bytes in r. If r is nil, it returns zero. 
CharacterLength: procedure [r: Reader] returns [cardinal]; 

CharacterLength returns the number of logical characters in r. Floating accent characters 
are treated as separate logical characters. If r is nil it returns zero. If r is a valid reader, 
then ByteLength(r] a 0 iff CharacterLength[r] ■ 0. If r contains an invalid encoding, 
CharacterLength will raise the error invaiidEncoding. 

Dereference: procedure [r: Reader] returns [rb: ReaderBody]; 

Dereference returns null ReaderBody if r is nil and r | otherwise. 

Empty: procedure [r: Reader] returns [boolean] > inline 

Empty returns true if r is NIL or ByteLength(r] a 0. 

Readerinfo: procedure [r: Reader] returns [context: Context, startsWith377B: boolean] ; 

Readerlnfo returns the context of the reader and whether the first byte of the reader is 
377B, the character set shift code. 

67JS.5 Accessing Characters 

Bcicause of the large number of characters in the character set standard and the way they 
are encoded, it is normally not possible to access characters of a reader by indexing. 
Instead, a number of operations are provided to access characters. 

Character: type ■ xchar.Character; 

Tirst: PROCEDURE [r: Reader] returns [c: Character]; 

First returns the first logical character. It is equivalent to NthCharacter[s, 0] but is usually 
more efficient. If Empty[r] then XChar.not is returned. It may raise the InvaiidEncoding 
error. 

NthCharacter: procedure [r: Reader, n: cardinal] returns [c: Character]; 

NthCharacter returns the nth logical character. Floating accent characters are treated as 
separate logical characters. First should be used if n = 0. If CharacterLength[r] < ■ n then 
XChar.not is returned. It may raise the InvaiidEncoding error. 

Lop: PROCEDURE [r: Reader] returns [c: Character]; 

Lop removes the first character from the front of a reader and returns it. If r is empty it 
returns XChar.not. If r contains one logical character. Lop sets r to be empty and returns 
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the first logical character. Otherwise, Lop modifies r to point to the second logical character 
and returns the first. It may raise the InvalidEncoding error. 

Map: PROCEDURE [r: Reader, proc: MapCharProc] returns [c: Character]; 

MapCharProc: type « proc [c: Character] returns [stop: boolean]; 

Map enumerates the reader, calling proc once for each character in r. If proc returns true 
it returns that character; otherwise it returns XChar.not. It is equivalent to: 

FOR i: CARDINAL IN [O..CharacterLength[r]) do 

IF proc[c *~ NthCharacter(r, i]] then return(c]; endloop 
RETURN[XChar.not] ; 

Map may raise the InvalidEncoding error. 

67.2.6 Errors 

Error: error [code: ErrorCode] ; 

ErrorCode: type » { 

invaiidOperation, muitipleCharSets, tooMahyBytes, invalidParameter}; 

i nval idOperation an invalid operation has been attempted. 

multipieCharSets InitBreakTable has been called with a reader that contains multiple 
character sets. 

tooManyBytes a long string has been passed to From STRING or 
WriterBodyFromSTRING and the string contains too many bytes. 
These operations use the string as the byte pointer so the offset is non- 
zero, reducing the number of bytes it may hold. This is also raised by 
CopyReader for a similar reason. 

invalidParameter. The term invalidParameter means an operation has been invoked 
with an invalid parameter. 

InvalidEncoding: error [invalidReader: Reader, firstBadByteOff set: cardinal] ; 

The error InvalidEncoding is raised by operations when they detect a sequence of bytes that 
is not a valid character encoding. While two character set shifts with no intervening 
character is an invalid encoding according to the character standard, only ValidateReader 
will raise InvalidEncoding if it detects that case. The other operations will ignore the first 
character set shift. Invalid encodings include ending with a character yet shift or partial 
character set shift and having a non-zero byte following two 377B bytes. 

67.2.7 Conversion to Readers 

ReaderFromWriter: procedure [w: Writer] returns [Reader] ■ inline ... ; 

ReaderFromWriter provides a conversion from the type Writer to the type Reader. This 
operation takes advantage of the fact that the ^rst part of writer bodies are bit-wise 
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compatible with reader bodies, and hence this operation simply loopholes the writer into 
the reader. 

FromBlock: procedure [ 

block: Environment.Biock, context: Context 4-vaniilaContext] returns [ReaderBody]; 

FromBlock returns a reader body that describes the block. 

FromChar: procedure [char: long pointer to Character] returns [ReaderBody]; 

FromChar returns a reader body that describes the character. The pointer to the character 
must remain valid for the lifetime of the reader body. 

FromNSString: procedure [s: NSString.String, homogeneous: boolean false] 
RETURNS [ReaderBody]; 

FromNSString returns a reader body that describes the characters in the NSString. The 
context of the reader body will be [suffixSize: 1, homogeneous: homogeneous, prefix: 0). 

FromSTRiNG: procedure [s: long string, homogeneous: boolean false] 
RETURNS [ReaderBody]; 

FromSTRING returns a reader body that describes the characters in the long string. The 
context of the reader body will be [suffixSize: 1, homogeneous: homogeneous, prefix: 0]. 
This operation may raise Error[tooManyBytes] if the string contains more than 
Cardinallast - StringBody.siZE * Environm«nt.bytesPerWord bytes. 

67.2.8 Reader Allocation 

CopyReader: procedure [r: Reader, z: uncounted zone] returns [new: Reader]; 

CopyReader makes a copy of the reader body and characters of r, allocating from z as a 
single allocation unit, the byte sequence for the characters, and the reader body. Note that 
this operation returns a reader while all other operations in this interface that create a 
reader or reader body return the reader body. The reason is to avoid a double allocation 
problem in which the byte sequence and reader body are allocated from two separate nodes. 
FreeReaderBytes can be used to free the new reader and the associated bytes. Note: This 
operation may raise Error[tooManyBytes] if the reader contains more than CARDiNAL.LAST - 
ReaderBody .SIZE * Environinent.bytesPerWord bytes. Errors in allocating from the zone are 
allowed to propagate. 

CopyToNewReaderBody: procedure [r: Reader, z: uncounted zone] returns [ReaderBody]; 

CopyToNewReaderBody allocates a copy of the bytes of r using z and returns a reader body 
describing them. If r is nil it returns nullReaderBody. Errors in allocating from the zone are 
allowed to propagate. 

FreeReaderBytes: procedure [r: Reader, z: uncounted zone]; 

FreeReaderBytes may be used to free the storage allocated by CopyReader and 
CopyToNewReaderBody. If r is non-NiL and z is non-NiL, it frees r.bytes to the zone. When 
the reader has been obtained from CopyReader, FreeReaderBytes will free the single 
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allocation unit that contains both the reader body and byte sequence. When the reader has 
been obtained from CopyToNewReaderBody, FreeReaderBytes will free the allocation unit 
that contains the byte sequence but will not free the reader body. Errors in freeing to the 
zone are allowed to propagate. 

67.2.9 Simple Writer Operations 

ClearWriter: procedure [w: Writer]; 

ClearWriter makes w empty. It is analogous to the long string statement s.length *- 0. 

Writerlnfo: procedure [w: Writer] 

RETURNS [unused: cardinal, endContext: Context, zone: uncounted zone]; 

Writerlnfo returns the number of allocated but unused bytes of a writer as well as its 
endContext and its zone. 

67.2.10 Conversion to Writers 

WriterBodyFromBlock: procedure [blocic: Environm«nt.Bloci(, inUse: cardinal <-0] 
RETURNS [WriterBody]; 

WriterBodyFromBlock returns a writer body that describes the block. The writer body's 
offset and maxLimit fields are set from the block's startlndex and stoplndexPlusOne fields, ^^ni^ 
respectively. The inUse parameter is used to set the limit field of the writer body. If the 
block's pointer is nil or inllse is larger than the number of bytes in the block, 
Error[invalidParameter] is raised. 

WriterBodyFromNSString: procedure [ 

s: NSString.String, homogeneous: boolean «- false] returns [WriterBody]; 

WriterBodyFromNSString returns a writer body that describes the characters in the 
NSString. Its context is [suffixSize: 1, homogeneous: homogeneous, prefix: 0]. 

WriterBodyFromSTRlNG: procedure [ 

s: LONG string, homogeneous: boolean false] returns [WriterBody]; 

WriterBody FromSTRING returns a writer body that describes the characters in the long 
STRING. Its context is [suffixSize: 1, homogeneous: homogeneous, prefix: 0]. This 
operation may raise Error[tooiVlanyBytes] if the string contains more than cardinallast • 
StringBody.siZE * Environment. bytesPerWord bytes. 

67.2.11 Writer Allocation 

NewWriterBody: procedure [maxLength: cardinal, z: uncounted zone] 
RETURNS [WriterBody]; 

NewWriterBody allocates a byte sequence that has room for maxLength bytes using z and 
returns an empty writer body that contains the bytes. Errors in allocating * 
ByteSequence[maxLength] from the zone are allowed to propagate. 
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CopyToNewWriterBody: procedure [ 

r: Reader, z: uncounted zone, endContext: Context unknownContext, 
extra: cardinal <-01 returns [w: WriterBody]; 

CopyToNewWriterBody allocates a byte sequence that has room for BiyteLength[r] •«• extra 
bytes using copies the bytes of r into the newly allocated byte sequence, and returns a 
writer body that contains the bytes. The end context of the writer body is endContext. 
Errors in allocating from the zone are allowed to propagate. 

ExpandWriter: procedure [w: Writer, extra: cardinal]; 

ExpandWriter assures that at least extra bytes are available in the writer's bytes. If 
w.zone is nil, then ErrortinvalidOperation] is raised. Errors in allocating a new byte 
sequence if required are allowed to propagate. 

FreeWriterBytes: procedure [w: Writer]; 

FreeWriterBytes may be used to free the byte sequence of a writer as long as it was 
allocated from the writer's zone. It may be used to free the byte sequence of writers created 
by CopyToNewWriterBody and NewWriterBody. If w is non-NiL and w.zone is non-NiL, it 
frees w.bytes to the zone. Note that it does not free the writer body. Errors in freeing to the 
writer's zone are allowed to propagate. 

67.2.12 Comparison of Readers 

Equal : procedure [r1 , r2: Reader] returns [boolean}; 

Equal returns true if and only if the number of logical characters is equal and the strings 
match when compared character by character, i.e., effectively CharacterLength[r1] » 
CharacterLength(r2l and NthCharacter(r1, i] ■ NthCharacter(r2, i] for i in the range [0.. 
CharacterLength[r1]). It may raise the InvalidEncoding error. 

Equivalent: procedure [r1, r2: Reader] returns [boolean]; 

Equivalent returns true if and only if the number of logical characters is equal and the 
strings match when compared character by character, ignoring case. It is equivalent to: 

IF CharacterLength[r1] # CharacterLength[r2] then return(false]; 
FOR I: CARDINAL IN [O..CharacterLength[r1]) do 

IF Oecase[NthCharacter[r1, i]] # Oecase(NthCharacter[r2, i]] then return(false]; 

ENOLOOP: 
RETURNfTRUE ]. 

Equivalent may raise the InvalidEncoding error. 

SortOrder: TYPE « machine dependent { 

standard(O), spanish(1), swedish(2), danish(3), firstFree(4), nult(377B)}; 

SortOrder is a parameter to Compare and CompareStringsAndStems that specifies the sort 
order, danish, Spanish, and Swedish differ from standard only in some characters in 
character set zero. 
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Compare: procedure [ 

r1, r2: Reader, ignoreCase: boolean 4-true, sortOrder: SortOrder f- standard] 
RETURNS [Relation]; 

CompareStringsAndStems: procedure [ 

r1, r2: Reader, ignoreCase: boolean 4-true, sortOrder: SortOrder «- standard] 
RETURNS [relation: Relation, equalStems: boolean]; 

Relation: TYPE ■ {less, equal, greater}; 

Compare and CompareStringsAndStems compare two readers. They return a relation 
indicating the sorted relationship of their arguments with the case of characters optionally 
ignored during the comparison. In CompareStringsAndStems, equalStems will be true if 
both readers are equal up to the length of the shorter. They may raise the InvalidEncoding 
error. 

67.2.13 Numeric Conversion of Readers 

ReaderToNumber: procedure [ 

r: Reader, radix: cardinal <- 10, signed: boolean <- false] returns [long integer]; 

ReaderToNumber converts the characters in the reader to a number. If radix is other than 
8, 10, or 16, XString.Error[invalidOperation] is raised. The syntax for a number is: 

{*'\'+}{baseNumber}{'b\'B\'d\'D\'h\'K}{scaleFactor} 

where {} indicates an optional part and "1" indicates a choice, and baseNumber and 
scaleFactor are sequences of digits. The value returned is ± baseNumber * radix ** 
scaleFactor. The radix depends on the contexts of r and radix. If r ends with a 'B or Hb, radix 
is 8; if it ends with a 'D or 'd, radix is 10, if it ends with a Ti or 'H, radix is 16; otherwise it is 
radix. The number scaleFactor is always expressed in radix 10. If r does not have valid 
form, or r does not contain any characters, or radix is 8 and non-octal digits are used, or 
signed is false and the reader contains a minus sign, the signal InvalidNumber is raised. If 
it is resumed, the operation returns zero. If signed is false and the number would overflow 
232-1 or signed is true and the number is not in the range [-231 231), the signal Overflow 
is raised. If it is resumed, the operation returns zero. ReaderToNumber may raise the 
InvalidEncoding error. 

ReaderToNumberX: procedure [ 

r: Reader, radix: cardinal 4r- 10, signed: boolean 4- false, 
numberParms: XDigits-NumberParms 4-XDigits.defaultNumberParms] 

RETURNS [long INTEGER]; 

ReaderToNumberX is the same as ReaderToNumber except that the numberParms 
parameter is added. If radix is other than 10, numberParms. representation and 
numberParms.thousandsSep will be ignored. See the XDigits chapter for more details. 
Fine Point: This procedure is currently exported through XStringX2. 

InvalidNumber: signal; 
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The signal InvalidNumber is raised by the string to number operations when the string is 
the wrong syntax for a number. Resuming this signal results in the operation returning 
zero. 

Overflow: signal; 

The signal Overflow is raised by the string to number operations when the string describes 
a number that is too large. Resuming this signal results in the operation returning zero. 

67.2.14 Character Scanning 

ScanForCharacter: procedure [r: Reader, char: Character, option: BreakCharOption] 
RETURNS [breakChar: Character, front: ReaderBody] 

BreakCharOption: TYPE ■ {ignore, appendloFront. leaveOnRest}; 

ScanForCharacter scans the string for the first instance of char. If char is found in r, the 
characters before it will be described by front and the characters after it will be described 
by-r. char will be on the end of front, discarded, or left on the front of r| if option is 
appendToFront, ignore, or leaveOnRest, respectively, char will be returned as breakChar. 
If it does not encounter char in r, then front will be equal to r f as it was when the 
procedure was invoked and r f will be updated to be 0 characters loilg. xchar.not will be 
returned as breakChar. ScanForCharacter may raise the InvalidEncoding error. 

Scan: procedure [r: Reader, break: BreakTable, option: BreakCharOption] 
RETURNS [breakChar: Character, front: ReaderBody]; 

BreakTable: TYPE ■ long pointer to BreakTableObject; 

BreakTableObject: type a record 
otherSets: StopOrNot stop, 
set:Environment.Byte <-0, 

codes: packed array [0..256) of StopOrNot ^ ALL[not]]; 
StopOrNot: type ■ {stop, not} «- not; 

Scan is like ScanForCharacter except that it can scan for any number of character codes in a 
particular character set. The BreakTable defines which character codes of a character set 
are scanned for. Scanning is searching for the first character, c, such that 

(xchar.Set[c] ■ break.set and break.codes[xchar.Code[c]] ■ stop) or 
(xchar.Set[c] # break.set and break.otherSets ■ stop). 

The disposition of the character that terminates scanning depends on option as in 
ScanForCharacter. If the character terminated scanning because it was in a different 
character set, xchar.not will be returned as breakChar. Scan may raise the InvalidEncoding 
error. 

InitBreakTabie: procedure [ 

r: Reader, StopOrNot: StopOrNot, otherSets: StopOrNot] 
RETURNS [break: BreakTableObject]; 
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InitBreakTable initializes a BreakTableObject to stop (or not stop) on the characters of r 
depending on stopOrNot. If r has multiple character sets, Error[muitipieCharSets] is raised. 
InitBreakTable may raise the InvalidEncodlng error. 

67.2.15 Other Reader Operations 

ComputeEndContext: procedure [r: Reader] returns [c: Context]; 

ComputeEndContext returns the context of the last character in r. If CharacterLength{r] 
■ 0 then emptyContext is returned. ComputeEndContext may raise the InvalldEncoding 
error. 

OescribeReader: Coun'er.Oescnption; 

OescribeReader is a Courier description routine. It is provided for clients that need to 
serialize and deserialize readers. 

DescribeReaderBody: Couri«r.Oescrlption; 

DescribeReaderBody is a Courier description routine. It is provided for cliients that need to 
serialize and deserialize readers bodies. 

Run: PROCEDURE [r: Reader] returns [run: ReaderBody]; 

Run is like Lop except that it deals in homogeneous runs of characters instead of single 
characters. It will return a reader body describing the first homogeneous run of r and 
update r to remove the run. If Empty[r] it returns nullReaderBody. It may raise the 
InvalldEncoding error. 

ValidateReader: procedure [r: Reader]; 

VaiidateReader checks the bytes of r to ensure that it is a valid encoding. If it is not a valid 
encoding, the error InvalldEncoding is raised. Possible invalid encodings include ending in 
a character set shift with no character or following two successive 377B bytes by a non-zero 
byte, null run, two character set shifts with no intervening character, is an invalid 
encoding that is checked by VaiidateReader. If the offset is greater than the limit or the 
byte pointer is nil and the offset and limit are not equal, then Error(invalidParameter] is 
raised. 

67.2.16 Appending to Writers 

The operations in this section append to writers. When there is insufficient space in the 
writer to hold the bytes to be appended, the operations attempt to allocate from the writer's 
zone a new byte sequence of sufficient size. If there is insufficient space and the writer's 
zone is nil, the signal InsufficientRoom is raised. If it is resumed, the operations will 
append as many characters as will fit. Errors resulting from allocating from the zone are 
allowed to propagate. An expanded set of appending operations are available using the 
XFormat interface. 
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AppendReader: procedure [ 

to: Writer, from: Reader, f romEndContext: Context ^ unknownContext, 
extra: cardinal 4-0]; 

AppendReader appends the reader to the writer. If either the reader or writer is nil, this 
operation simply returns. The end context of the writer is updated to f romEndContext if it 
is not unknownContext and ComputeEndContext(r] otherwise. The signal 
InsufficientRoom may be raised as described above. 

AppendChar: procedure [to: Writer, c: Character, extra: cardinal «- 0]; 

AppendChar appends the character to the writer. If the writer is nil, this operation simply 
returns. The signal InsufficientRoom may be raised as described above. If it is resumed, 
nothing is appended. 

AppendStream: procedure [ 

to: Writer, from: stream.Handle, nBytes: cardinal, 
fromContext: Context unknownContext, extra: cardinal 4-0] 
RETURNS [bytesTransf erred: cardinal]; 

AppendStream appends nBytes from the stream from to the writer. If either the stream or 
writer is nil, this operation simply returns. The end context of the writer is updated to 
f romEndContext if it is not unknownContext and ComputeEndContext[r] otherwise. The 
signal InsufficientRoom may be raised as described above. If it is resumed, as much of the 
reader as will fit in the space available is appended. AppendStream returns the actual 
number of bytes transferred. 

Note: There is currently a bug in the interface such that the fromContext parameter is 
defaulted to vaniilaContext instead of unknownContext. 

AppendSTRI NG: procedure [ 

to: Writer, from: long string, homogeneous: boolean <- false, extra: cardinal <- 0]; 

AppendSTRI NG appends the string to the writer. If either the string or writer is nil, this 
operation simply returns. The end context of the writer is updated to vaniilaContext if 
homogeneous is true, otherwise its value is computed from the parameter from. The 
signal InsufficientRoom may be raised as described above. 

InsufficientRoom: signal [needsMoreRoom: Writer, amountNeeded: cardinal]; 

The signal InsufficientRoom is raised by the append operations when the writer does not 
have enough room to contain the appendee and the writer's zone is nil. Resuming this 
signal will result in as much as possible being appended. 

AppendExtensionlf Needed: procedure [to: Writer, extension: Reader] 
returns [didAppend: boolean]; 

AppendExtensionlf Needed checks to see if there is a period somewhere in the writer other 
than the last character. If there is, false is returned. If not, it appends a period if the writer 
does not already end in one, then appends extension and returns true. AppendChar and 
AppendReader are used to append and they may raise InsufficientRoom. 



67-13 



67 



XString 



67.2.17 Editing Writers 

Piece: procedure [r: Reader, firstChar, nChars: cardinal] 
RETURNS [piece: ReaderBody, endContext: Context]; 

Piece returns a reader body that describes the firstChar through firstChar + nChars logical 
characters of r. piece will descfribe as many characters of r that are in that range, possibly 
none if CharacterLength[r] is less than or equal to firstChar. The context of the last 
character of piece is also returned. It may raise the InvalidEncoding error. 

ReplacePiece: procedure [ 

w: Writer, firstChar, nChars: cardinal, r: Reader, 
endContext: Context unlcnownContext]; 

ReplacePiece is an editing operation for writers. It replaces nChars of w starting at 
firstChar with the characters of r. nChars may be zero and r may be empty. If the reader is 
not empty, endContext is needed to update the end context of the writer if the piece 
replacement is at the end, or to determine if there needs to be a character set shift between 
the bytes of r and the (firstChar ♦ nChar)th character of w. If endContext is 
unlcnownContext it will be computed from r. The signal InsufficientRoom may be raised as 
described above if the operation resulted in a net addition of bytes. ReplacePiece may raise 
the InvalidEncoding error. 

67.2.18 Conversion from Readers 

Block: PROCEDURE [r: Reader] returns [block: Environment. Block, context: Context] ; 

Block returns both a block that describes the bytes in r as well as the context of r. This 
operation may be used by clients that need to examine the bytes directly. Note: The bytes 
of the block should not be written. 

NSStringFromReader: procedure [r: Reader, z: uncounted zone] 
RETURNS [ns: NSString.String] ; 

NSStringFromReader creates an NSString.String from a reader. It always copies the bytes of 
the reader into a new allocation unit allocated from the zone. The resulting string should 
be deallocated using operations from the NSString interface. Errors from allocating from 
the zone are allowed to propagate. 

67.2.19 Reverse Character Operations 

ReverseMap: procedure [r: Reader, proc: MapCharProc] returns [c: Character]; 

ReverseMap is similar to Map, except it enumerates the characters in reverse order. It is 
less efHcient than Map because encoding characters makes backward scanning difficult. It 
may raise the InvalidEncoding error. 

ReverseLop: procedure [ 

r: Reader, endContext: long pointer to Context, 
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backScan: BackScanCiosure [nil, nil]] 
RETURNS [c: Character]; 

BackScanCiosure: type ■ record [proc: BackScanProc, env: long pointer]; 

BackScanProc: type ■ procedure [beforePos: cardinal, env: long pointer] 
returns [pos: cardinal, context: Context]; 

ReverseLop is similar to Lop, except it takes characters off the end of the reader. It is less 
efHcient than Lop because encoding characters makes backward scanning difficult. If the 
reader is empty, it retiu-ns xchar.not. If endContext t is not unknownContext, then it must 
be correct. It may be changed by a call to ReverseLop. If ReverseLop backs up over a 
character set shift, it will set endContext f to unknownContext. It may raise the 
I nval idEncoding error. 

The BackScanCiosure and BackScanProc provide a way for the client to inform ReverseLop 
of the context in effect before a character set shift. If endContext t is unknownContext, 
then backScan. proc is called with a byte offset before which it desires a context and 
backScan. env. It should return a context for some position before the passed one, as well as 
the actual position corresponding to that context. Simple clients of ReverseLop need not 
provide a BackScanCiosure. It is provided for clients that have information about location 
of character set changes within the reader. 

67.3 Usage/Examples 

67.3.1 Designing Interfaces with Readers 

Designing interfaces to use readers is more complicated than long strings. The biggest 
complication is the two-level allocation scheme involving readers reader bodies -> bytes. 
In most cases, the bytes are relatively static and are relatively easy to deal with. The main 
problem is determining whether to use a reader or a reader body. It helps to keep in mind 
the following guideline: keep reader bodies to describe the bytes. Save a pointer to a string 
by putting the reader body, not the reader, in the data structure. This way, one doesn't 
have to worry about who owns the storage for the reader body. Consider the following 
interface fragment: 

Handle: type ■ long pointer to Object; 

Object: type ■ record [ 
next: Handle, 
count: cardinal, 
name: xstring.ReaderBody]; 

AddAnother: procedure [name: xstring. Reader]; 

Instead of storing the name in the object as a reader, it is stored as a reader body. A reader 
is quickly generated when needed by the expression @h.name. 

Another guideline is for a procedure to take a reader and return a reader body. The idea is 
that passing readers as parameters reduces the number of words of parameters. Returning 
reader bodies allows the client to manage the storage for the reader body. 
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A third guideline is that clients should be able to pass pointers to local reader bodies. If an 
implementation kept strings passed to it by saving readers, clients would have to allocate 
the reader body from permanent storage, not from the local frame. If implementations keep 
reader bodies instead of readers, passing @localReaderBody will not result in dangling 
pointers. For example, consider the following fictional procedure that renames a file: 

RenameFtie: procedure [oldName:xstring.Reader] ■ { 
rb: xstring.ReaderBody; 
rb Someint«rfac«.GetNewNamen; 
file 4- Someinterface.LookupByName[oldName]; 
Som«interfa€9.Rename[fiie: file, newName: @rb]}; 

The procedure RenameFiie takes a reader that it simply passes to another operation. While 
taking a reader body is equilvalent, it is more efficient to take a reader, particularily when 
strings are just being passed around. The operation GetNewName returns a reader body. If 
it returned a reader, it would have to define where the storage for the reader body was kept. 
Either it would have to be global, or it would have to be deallocated from a known place 
after RenameFiie was done with it. It is just simplier to return reader bodies than to deal 
with the allocation problems of reader bodies. It is hard enough to make sure ownership of 
the bytes is handled correctly. The new name to the Rename operation is a pointer to a 
local reader body. Rename should copy the reader body (and the bytes) if it intends to save 
the characters. 

Warning: Designing interfaces that do not allow passing pointers to local reader bodies 
should be avoided. 



67.3.2 Using Readers 



One of the simple things to do with strings is to pass string literals. Because there is no 
compiler support for XString, it is harder to do. The code fragment below gives an example 
of how to pass string literals: 

GetUserCmFiie: PROCEDURE RETURNS [file: Someinterface.Filel^andle] ■ { 
rb: xstring.ReaderBody xstring.FromSTRING[''User.cm''L]; 
file«-Soineinterface.LookupByName[name: @rb]}; 

Looking at all the characters in a string for something like switch processing is another 
common operation: 

Options: type ■ record [debug, verify, start: boolean false]; 

ParseSwitchesI : procedure [r: xstnng.Reader] returns [options: Options] a { 
rb: xstring.ReaderBody xstring.Dereference[r]; 
c: xstring-Character; 
sense: boolean «~ true; 

WHILE (C ^ XString.L0p[@rb]) # XChar.nOt DO 

select c from 

'd.ORO a > {options.debug sense; sense true}; 
'v.ord ■ > {options. verify <- sense; sense «- true}; 
's.ORO ■ > {options.start sense; sense 4- true}; 
'-.ORD ■ > senses- false; 
ENDCASE ■ > sense <- true; 
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ENDLOOP; 

return}; 

ParseSwitchesI uses Lop to look at each character of r and set the appropriate option. 
Because Lop changes the reader body to remove the first character, ParseSwitchesI uses 
Dereference to copy the reader body to a local variable. 

The operations Lop, Run, ScanForCharacter, and Scan all update the reader body of their 
reader parameter. If the reader body must not be altered, it should be copied as in the 
above example. 

ParseSwitches2: procedure [r: xstring.Reader] returns [options: Options] a { 
sense: boolean <-true; 
proc: xstring.MapCharProc ■ { 
select c from 

'd.ORO ■ > {options.debug sense; sense «~ true}; 
'v.ORD ■ > {options. verify <- sense; sense true}; 
's.ORD ■ > {options.start <- sense; sense ^ true}; 
'•.ORD a > sense *- false; 
ENDCASE ■ > sense 4- true; 

RETURN[stOp: FALSE]}; 

n 4-xstring.Map[r: r, proc: proc]; • 
return}: 

ParseSwitches2 uses Map to look at each character of r and set the appropriate option. 

67.3.3 Simple Parser Example 

Below is a simple program that accepts a sequence of characters from a procedure and 
parses them into tokens. It collects characters one a a time and appends them to the writer 
buffer. If the string of characters is empty, it returns a keyword token o{ invalid. If the first 
character is a digit, it returns a number token, converting the string into the number. 
Otherwise it compares the string with the four keywords. If it is not a keyword, it copies the 
string from the buffer to a new reader and returns the id token. 

~ Example.mesa 

DIRECTORY 

XString using [ 

AppendChar, Character, ClearWriter, Empty, Equai, First, InvalidNumber, 
NewWriterBody, OverFlow, Reader, ReaderBody, ReaderFromWriter, 
ReaderToNumber, WriterBody]; 

Example: PROGRAM IMPORTS XString a { 
OPEN XString; 

TokenClass: type ■ {l<eyword, id, number}; 

Keyword: type « {begin, end, do, endioop, eof, invalid}; 

Token: type ■ record [ 

select class: TokenClass from 

keyword ■ > [keyword: Keyword], 

id ■ > [id: ReaderBody], 
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number ■ > [number: long integer], 
enocase]; 

Input: TYPE ■ procedure RETURNS [Character]; 
eof , space: Character ■ . . . ; 

keywords: long descriptor for array Keyword[begin..endloop] OPReaderBody a . . . ; 
zone: uncounted zone 

buffer: WriterBody 4- NewWriterBody[maxLength: 40, z: zone] ; 

Parse: procedure [input: Input] returns [token: Token] ■ { 
r: Reader ReaderFromWriter[@buffer]; 
c: Character; 
ClearWriteribuffer]; 

DO 

select (c 4- input[]) from 
space ■ > exit; 

eof M > RETURN([keyword(iF Empty[r] then invalid ELSE eof]]]; 
endcase a > AppendChar[@buffer, c]; 
endloop; 

IP Emptyfr] then RETURN[[keyword[invalid]]; 
IF First(rl in ['0.ord..'9.oro] then £ 

token 4- [number[ReaderToNumber(r, 10 ! 

InvalidNumber, Overflow > > {token 4- [keyword(invaiid]]; continue}]]]; 

return}; 

select TRUE FROM 

Equal[r, @keywords[begin]] m > token 4- [keyword[begin]]; 
Equal[r, @keywords[end]] ■ > token 4- [keyword[end]]; 
Equai[r, @keywords[do]] ■ > token 4- [key word[do]]; 
Equal[r, @keywords[endloop]] « > token 4-[keyword[endioop]]; 
ENDCASE ■ > 

token 4-> [id[CopyToNewReaderBody(r: r,z: zone]]]; 
return}; 
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Item Page 


Item 


Page 


AppendChar: procedure 


13 


FromSTRlNG: procedure 


7 


AppendExtensionifNeeded: procedure 


13 


InitBreakTable: procedure 


12 


AppendReader: procedure 


13 


InsuffidentRoom: signal 


13 


AppendStream: procedure 


13 


InvalidEncodIng: error 


6 


AppendSTRING: procedure 


13 


InvaiidNumber: signal 


10 


BackScanClosure: type 


15 


Lop: procedure 


5 


BackScanProc: type 


15 


Map: procedure 


6 


Block: procedure 


14 


MapCharProc: type 


6 


BreakCharOption: type 


11 


NewWriterBody: procedure 


8 


BreakTable: type 


11 


NSStringFromReader: procedure 


14 


BreakTableObject: type 


11 


NthCharacter: procedure 


5 


Byte: type 


4 


nullReaderBody: ReaderBody 


4 


ByteLength: procedure 




nuilWrlterBody: WriterBody 


4 


Bytes: type 


4 


Overflow: signal 


11 


ByteSequence: type 


3 


Piece: procedure 


14 


Character: type 


5 


Reader: type 


3 


CharacterLength: procedure 


5 


ReaderBody: type 


3 


ClearWriter: procedure 


8 


ReaderFromWriter: procedure 


6 


Compare: procedure 


10 


Readerlnfo: procedure 


5 


CompareStringsAndStems: procedure 


10 


ReaderToNumber: procedure 


10 


ComputeEndContext: procedure 


12 


ReaderToNumberX: procedure 


10 


Context: type 


2 


ReadOniyBytes: type 


3 


CopyReader: procedure 


7- 


Relation: type 


10 


CopyToNewReaderBody: procedure 


7 


RepiacePiece: procedure 


14 


CopyloNewWriterBody: procedure 


9 


ReverseLop: procedure 


15 


Dereference: procedure 


5 


ReverseMap: procedure 


14 


OescribeReader: Courier. Description 


12 


Run: PROCEDURE 


12 


DescribeReaderBody: Couri«r.Description 


12 


Scan: procedure 


11 


Empty: procedure 


5 


ScanForCharacter: procedure 


11 


emptyContext: Context 


3 


SortOrder: type 


9 


Equal: procedure 


9 


StopOrNot: type 


11 


Equivalent: procedure 


9 


unknownContext: Context 


3 


Error: error 


6 


ValidateReader: procedure 


12 


ErrorCode: type 


6 


vanillaContext: Context 


3 


ExpandWriter: procedure 


9 


Writer: type 


4 


First: procedure 


5 


WriterBody: type 


4 


FreeReaderBytes: procedure 


7 


WriterBody From Block: procedure 


8 


FreeWriterBytes: procedure 


9 


WriterBodyFromNSString: procedure 


8 


FromBlock: procedure 


7 


WriterBodyFromSTRING: procedure 


8 


FromChar: procedure 


7 


Writerinfo: procedure 


8 


FromNSString: procedure 


7 
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68.1 Overview 

The XTime interface provides functions for acquiring and editing times into strings or 
strings into times. It provides the same function as the XDE Time interface but deals with 
xstring.Readers instead of long strings. 

68.2 Interface Items 

68.2.1 Acquiring Time 

Current: PROCEDURE returns [time: System.GreenwichMeanTime]; 

Current returns the current time. 

ParseReader: procedure [ 

r: xstring.Reader, treatNumbersAs: TreatNumbersAs <- dayMonthYear] 
RETURNS [time:system.GreenwichMeanTime, notes: Notes, length: cardinal]; 

Parse WithTem plate: procedure [r, template: xstring.Reader] 

returns [time: System.GreenwichMeanTime, notes: Notes, length: cardinal]; 

TreatNumbersAs: TYPE « {dayMonthYear, monthOayYear, yearMonthOay, 
yearOayMonth, day YearMonth, month YearDay}; 

The ParseReader procedure parses the reader r and returns a GMT time according to the 
Pilot standard. treatNumbersAs indicates how to interpret r. ParseWith Template parses r 
according to template, template serves as an interpreter for deriving time fields from r (see 
§ 68.3). The date syntax is a somewhat less restrictive version of RFC733; full RFC733 is 
recognized, plus forms like "month day, year'*, "mm/dd/yy", and variations with Roman 
numerals used for the month. The form ''year month day" is also accepted if the year is a 
full four-digit quantity. Forms with instead of significant space are also acceptable, as 
well as forms in which a delimiter (space or **-") can be elided without confusion. The time 
is generally assumed to be in RFC733 format, optionally including a time zone 
specification. In addition, am or pm may appear following the time (but preceding the time 
zone, if any), notes is interpreted as described below, length indicates the number of 
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characters consumed by the parser (that is, it is the index of the first character of the jilllk 
argument that was not examined by the parser). This procedure can raise the error ; 
Unintelligible. 

Notes: type ■ {normal, noZone, zoneGuessed, noTlme, timeAndZoneGuessed}; 

Notes is used as one of the return values from the call on ParseReader. normal means the 
value returned is unambiguous; noZone means that a time>of-day without a time zone 
indication was present. (The local time zone as provided by Systcm.LocalTlmeParameters is 
assumed.) zoneGuessed is returned instead of noZone if local time parameters are not 
available; the time zone is assumed to be Pacific Time (standard or daylight time is 
determined by the date). noTlme and timeAndZoneGuessed are equivalent to noZone and 
zoneGuessed respectively, where the time is assumed to be 00:00:00 (local midnight). 

Unintelligible: error [vicinity: gvroinal]; 

If ParseReader cannot reasonably interpret its input as a date, Unintelligible is raised; 
vicinity gives the approximate index in the input string where the parser gave up. 



68.2.2 Editing Time 

Append: procedure [ 

w: xstring.Writer,time: System.GreenwichMeanTime 4~defaultTime, 
template: xstrmg.Reader dateAndlime, Itp: LTP«~useSystem]; 

Append appends the time in human-readable form to w. template determines which fields 
are appended, itp provides the local time parameters (discussed below). 

Format: procedure [ 

xf h: XFormat.Handle NIL, time: System.GreenwichMeanTime <- defaultTime, 
template: xstring. Reader «- dateAndTime, Itp: LTP useSystem]; 

Format converts time to a string by calling XTime.Append using template to specify which 
template to use. xfh.proc is then called. If time is defaulted, the current time is used. 

Pack: procedure [unpacked: Unpacked, useSystemLTP: boolean 4- true] 
RETURNS [time: System.GreenwichMeanTime]; 

Pack converts unpacked into the Pilot-standard System.GreenwichMeanTime. 
useSystemLTP indicates that Pack should use the system's parameters. If the local time 
parameters are not available to Pilot, System.LocaiTimeParametersUnknown is raised. If 
unpacked is invalid, Invalid is raised. 



Packed: type ■ System.GreenwichMeanTime; 
Packed is retained for compatability. 

Unpack: procedure [ 

time: System.GreenwichMeanTime <-defaultTime, Itp: LTP <- useSystem] 

returns [unpacked: Unpacked]; 
Unpack converts time into its unpacked representation. If time is defaulted, the current 
time is used. Itp provides local time parameters. If the local time parameters are not 
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available to Pilot, System.LocalTimeParametersUn known is raised. If time is invalid. 
Invalid is raised. 

Unpaciced: type a recoro[ 

year: [0..2104], month: [0..12). day: [0..31], 

hour: [0..24), minute: [0..60), second: [0..60K 

weekday: [0..6], dst: boolean, zone: Syst«m.LocaiTimeParameters]; 

Unpacked values record dates by their pieces. The fields are filled by Unpack, described 
above, which operates on the time and date as kept internally by Pilot, year = 0 
corresponds to 1968. For month, January is numbered 0, l,and so forth. Days of the month 
have their natural assignments. For weekday, Monday is numbered 0. dst indicates 
Daylight Standard Time, zone indicates time zones. 

LTP: TYPE ■ RECOROf 

r: SELECT t: * from 
useSystem ■ > []« 

useThese a > [Ipt: System.LocalTimeParameters]] 
enocase]; 

LTP passes local time parameters to several procedures. Usually they are defaulted to the 
system's parameters. 

Invalid: error; 

68.2.3 Useful Constants and Variables 

dateAndUme: xstring.Reader; 
dateOniy: xstring.Reader; 
timeOniy: xstring.Reader; 

These variables are templates that are supplied by XComSoftMessage for use in the 
Append operation. 

defauitTime: System.GreenwichMeanTime ■ System.gmtEpoch; 

defaultTime always means the current time. 

useSystem: useSystem LTP « [useSystem[]]; 
useGMT: useThese LTP ■ [useThese[[west, 0, 0, 0, 0]]]; 

These local time parameters are exported for client convenience. 
68.3 Usage/Examples 

68.3.1 ParseReader Template Definitions 

The template for times is a reader with fields, using the standard definition of naming 
fields (that is, a number enclosed by angle bracket's). The definition of the fields for times 
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<1> 


Month as a number* 


<2> 


Day as a number* 


<3> 


Year as a four-digit number 


<4> 


Year as a two-digit number 


<5> 


Month name 


<6> 


Month name with a maximum of three characters 


<7> 


Hour as digits in range [0..12)* 


<8> 


Hour as digits in range [0..24)* 


<9> 


Minutes, always two digits, zero-filled (e.g., 23, 04) 


<10> 


Seconds, always two digits, zero-filled (e.g., 23, 04) 


<11> 


Day of week 


<12> 


Time zone 


<13> 


AMorPM 



* If the number begins with a 0, the number is zero-filled to two digits. 
Examples 

<2>-<6>-<4> <7>:<9> 18-Nov-83 8:36 

<2><5><3> 18 November 1983 

<2>-<6>-<4> <7>:<9>:<10> <12>«11» 18-Nov-83 08:36:42 PST (Friday) 

<7>:<9> <13> 8:36AM m 

< 08 >< 9 > hrs 0836 hrs 



68.3.2 Example 



— D^ta structure to record time in both Packed and Unpacked form. 
Data: type a record [ 

startTime: xstring. Reader Body 4-xstring.nullReaderBody, 
endTime: xstring. Reader Body 4-xstring.nuilReaderBody« 
pStartTime: XTim«.Packed 4-Systeni.gmtEpoch, 
pEndTime: XTim«.Packed 4-System.gmtEpoch]; 

» Retrieves, unpacks, stores, and displays the time. 
GetAndDisplayTime: PR0c[packTime: xTime.Packedl ■ { 

time: xTim«.Unpacked 4-xTim«.Unpack[packTime]; 

TimeDisplay [time.year, time.month, time.day]; 

}; 

ParseTimes: PR0c[data: Data] « { 
data.pStartTime «-XTime.ParseReader[@data.startTime ! 

xTime.Uninteiligible * > Error(BadStartTime, vicinity]].time; 
data.pEndTime 4-XTinie.ParseReader[@data.endTime ! 

XTime.Uninteiligible ■ > Error[BadEndTime, vicinity]].time; 

}; 

— Parses time into an xstring. ReaderBody 
PackedToString: PR0C(time: System.GreenwichlVleanTime] 
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RETURNS [rb:XString.ReaderBody<-XString.nuilReaderBody] ■ { 
template: xstring.ReaderBody <-xstring.FromSTRlNG[ 

••<2>-<6>-<4> <8>:<9>"L1; 
wb: xstring.WriterBody «-xstring.NewWriterBody[24, zone]; 
-XTime.Append[ @wb, time, ©template ]; 

rb 4- xstring.CopyToNewReaderBody[xstring.ReaderFromWriter[@wb], zone]; 
xstring.FreeWrlterBytes[@wb]; 

}; 
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68.4 Index of Interface Items 



Item Page 

Append: procedure 2 

Current: procedure 1 

dateAndTime: xstring.Reader 3 

dateOniy: xstring.Reader 3 

defauitTime: constant 3 

Format: procedure 2 

Invalid: error 3 

LTP: TYPE ^ 3 

Notes: type 2 

Pack: PROCEDURE 2 

Packed: type 2 

ParseReader: procedure 1 

ParseWithTemplate: procedure 1 

timeOniy: xstring.Reader 3 

TreatNunnbersAs: type 1 

Uninteiiigibie: error 2 

Unpack: procedure 2 

Unpacked: type 3 

useGMT: constant 3 

useSystem: constant 3 
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69.1 Overview 

The XToken interface provides general scanning and simple parsing facilities for collecting 
tokens from a character input stream. 

The basic data structure is the Object, which encapsulates the source of characters to be 
parsed. It contains a procedure that returns the next character in the input stream and the 
final character that is read from the input stream. 

The basic operations collect characters from the input stream into tokens. Clients can 
•^1^ define arbitrary token classes by using filters. Clients can define their own filters or use 

one of the standard filters provided by XToken. Frequently, some portion of the input 
stream, such as blanks, are only delimiters and are usually skipped when collecting a 
token. The type SkipMode defines the options for skipping characters. Quoted tokens are a 
feature provided by XToken. By using procedures to define opening- and closing-quote 
characters, XToken allows the client to define a large number of quoting schemes. Several 
common quote procedures are supplied. 

XToken provides operations that collect standard tokens such as boolean and numeric 
values. It also provides built-in handles that understand xstring. Readers and stream.Handies 
as sources of characters. 

Operations that return a reader body allocate their storage from the implementation's own 
heap. Clients should call FreeTokenString to release this storage. 

69.2 Interface Items 

69.2.1 Character Source Definitions 

Handle: type a long pointer to Object: 

Object: type 3 MACHINE DEPENDENT RECORD [ 

getChar(0):GetCharProcType, break(l): xchar.Character 4-o]: 
GetCharProcType: type » procedure [h: Handle] returns [c: xchar.CharacterJ; 
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The Object encapsulates the source of characters to be parsed. The XToken package uses 
the getChar field to obtain the stream of characters. It assumes that the source has been 
exhausted when getChar returns xchar.nuil or xchar.not. XToken uses the break field to 
record the final character that it reads. It records the final character because there is no 
way to put back a character into the character source. It must read one character beyond 
the token it is parsing to ensure that it has reached the end of the input. If it simply 
returned the token, this character would be lost. Since the XToken package stores the last 
character in the Object, that character is available to the client. The client can ignore it, 
inspect it to decide what to parse next, or put it back into the character source. 

A GetCharProcType provides a stream of characters to be parsed. It should return either 
xchar.nuil or xchar.not when the stream of characters has been exhausted. The Handle is 
passed into the GetCharProcType so that a client can hide instance data in his object. 
Although there is not an instance data field in Object, the client could loophole a pointer to 
a larger record that contained its data. 

69.2.2 Filter Definitions 

FilterProcType: type = procedure [ 

c: xchar.Character« data: FllterState] returns [inClass: boolean]; 

FiiterState: type « long pointer to StandardFliterState: 

StandardFilterState: type » array [0..2) of unspecified; 

A FilterProcType is the mechanism by which a client defines classes of characters. 
Procedures that use filters will call them once for each candidate character. The filter 
should return true if the character is in the class and FALSE otherwise. The FiiterState 
permits the filter to maintain the state of the parse. Operations that require a 
FilterProcType and FiiterState, will initialize the StandardFilterState to allIOJ. If the filter 
requires filter state but data is nil, the signal NIIData should be raised. 

Some clients' filters may need more than two words of state for their filter. In that case 
they should define a record that first contains a StandardFilterState, then define the 
additional space they need, and then loophole the filter state to a pointer to the record they 
defined. 

69.2.3 Skip Mode Definitions 

SkipMode: type » {none, whiteSpace, nonToken}: 

SklpMode controls what characters an operation will skip before collecting a token. 

none The term none means no characters should be skipped, and the token 

should start with the next character. 

whiteSpace The term whiteSpace means characters (space, carriage return, and tab) 
should be skipped before collecting the token. 

nonToken The term non Token means any characters that are not legal token 

characters should be skipped before collecting the token. 
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69.2.4 Quoted Token Definitions 

QuoteProcType: type » procedure [ 

c: xchar.Character] returns [closing: xchar.Character]; 

nonQuote: xchar.Character ■ . . . : 

QuoteProcType defines the procedure used by MaybeQuoted to recognize quoted tokens. If 
c is a quote character, it should return the corresponding closing-quote character. If c is not 
a quote character, it should return nonQuote. 

69.2.3 Built-in Handles 

ReaderToHandle: procedure [r: xstring.Reader] 
RETURNS [h: Handle]; 

ReaderToHandle creates a Handle whose source of characters are the characters in r. The 
bytes of r are not copied, so clients are responsible for synchronizing access to the reader 
with the XToken package. 

FreeReaderHandle: procedure [h: Handle] returns [nil: Handle]; 

FreeReaderHandle destroys a Handle created by ReaderToHandle. It does not destroy the 
underlying reader. It returns NIL. 

StreamToHandle: procedure [s: stream.Handle] returns [h: Handle]; 

StreamToHandle creates a Handle whose source of characters is a stream. The stream 
should signify the end of characters by raising the signal Stream. EndOfStream. 

FreeStreamHandle: procedure [h: Handle] returns [s: stream.Handle]; 

FreeStreamHandle destroys a Handle created by StreamToHandle. It returns the 
underlying stream. 

69.2.6 Boolean and Numeric Tokens 

Boolean: procedure [h: Handle, signalOnError: boolean <- true] returns [true: boolean]; 

Boolean parses the next characters of the source as a boolean constant. Valid Boolean 
values are "TRUE" or "FALSE," but unlike the Mesa language, case does not matter 
(*'true" and "false" are also acceptable). In case of a syntax error, the signal SyntaxError is 
optionally raised. If signalOnError is false, or SyntaxError is resumed, then false is 
returned for a syntax error. This procedure skips leading white space. 

Number: procedure [h: Handle, radix: cardinal, signalOnError: boolean <~ true] 
returns [u: long unspecified]; 

Number parses the next characters of the source as a number in radix radix. Numbers have 
the format specified in xstring.ReaderToNumber. In case of a syntax error, the signal 
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SyntaxError is optionally raised. If signalOnError is false, or SyntaxError is resumed, zero 
is returned for a syntax error. This procedure skips leading white space. 

NumberX: procedure [h: Handle, radix: cardinal, signalOnError: boolean <- true, 
numberParms: xoigits-NumberParms «- xoigits-numberParms] 
returns [u: long unspecified]; 

NumberX is the same as Number except that numberParms can be specified. See the 
XDigits chapter for more details. If radix is other than 10, numberParms.representation 
and numberParms.thoUSandsSep will be ignored. Fine Point: This procedure is currently exported 
through XTokanX. 

Decimal: procedure [ 

h: Handle, signalOnError: boolean <-true] returns [i: long integer]; 

Decimal is just like Number, but with a radix of 10. 

DecimaiX: procedure [ 

h: Handle, signalOnError: boolean ^ true, 

numberParms: XDigits-NumberParms 4- XDigits.numberParms] 

returns [i: LONG integer]; 

DecimaiX is just like NumberX, but with a radix of 10. See the XDigits chapter for more 
details. Fine Point: This procedure is currently exported through XTokenX. 

Octal: PROCEDURE [ 

h: Handle, signalOnError: boolean <- true] returns [c: long cardinal]; 
Octal is just like Number, but with a radix of 8. 

69.2.7 Basic Token Routines 
Filtered: procedure [ 

h: Handle, data: FilterState, filter: FilterProcType, skip: SkipMode ^whiteSpace, 
temporary: boolean true] 
returns [value: xstring.ReaderBody]; 

Filtered collects the token string defined by the client's filter. If the client-instance data 
parameter data is not nil, the first two words of data are set to zero before any calls are 
made to filter, filter is called with data once on each character until it returns false. The 
string returned, which may be xstring.nullReaderBody, must be freed by calling 
FreeTokenString. Leading characters are skipped according to the value of skip. If 
temporary is true, it is assumed that the string will be freed shortly, and no effort is made 
to use the minimum storage for it. If temporary is false, the minimum amount of storage is 
used, filter may raise NilData. 

FreeTokenString: procedure (s: xstring. Reader] returns [nil: xstring.Reader ^nil]; 

FreeTokenString frees bytes of the reader. It is used to free the strings allocated by Filtered, 
Item, and MaybeQuoted. It returns nil. 
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Item: procedure [ 

h: Handler temporary: boolean <- true] returns [value: xstring.ReaderBody]; 

Item returns the next token delimited by white space. Leading white space is skipped and 
the characters are collected until another white-space character is encountered. The string 
returned must be freed by calling FreeTokenString. If temporary is true, it is assumed that 
the string will be freed shortly, and no effort is made to use the minimum storage for it. If 
temporary is false, only as much storage is used for the string as is needed. 

MaybeQuoted: procedure! 

h: Handle, data: FllterState, filter: FilterProcType NonWhiteSpace, 
IsQuote: QuoteprocType Quote, skip: SkipMode whiteSpace. 
temporary: boolean 4-trueI 
returns [value: xstring.ReaderBody]: 

MaybeQuoted returns the next quoted token. The first candidate character is passed to 
IsQuote, which either returns nonQuote or the closing-quote character. If a closing-quote 
character other than nonQuote is returned, characters are collected in the token until the 
closing quote is encountered. If the input is exhausted before the closing quote is 
encountered, the signal UntermlnatedQuote will be raised. If it is resumed, MaybeQuoted 
returns the token collected up until that point. The closing-quote character may be 
included in the token by including two instances of the character in the input; that is, if 
MaybeQuoted encounters two closing-quote characters in a row, it will insert one closing- 
quote character in the token rather than terminating the token on the first closing quote. 
The outer quote characters are not part of the token and are discarded. If nonQuote is 
returned from the IsQuote procedure, the filter is used to collect characters the same way it 
is used in Filtered: filter is called with client-instance data parameter data once on each 
character until it returns false. In either case (quoted or filtered), the break character 
returned in the Handle is the character following the token. 

Leading characters are skipped according to the value of skip. 

If temporary is true, it is assumed that the string will be freed shortly and no effort is made 
to use the minimum storage for it. If temporary is false, only as much storage is used for 
the string as is needed. The string returned must be freed by calling FreeTokenString. 

Skip: procedure [ 

h: Handle, data: FilterState, filter: FilterProcType, ski pInClass: boolean true]; 

Skip is used to skip over characters. A filter is provided to define the class of characters, 
and the boolean skiplnClass indicates whether the characters to be skipped are those 
accepted by the filter or those rejected by it. If the client-instance data parameter data is 
not NIL, the Hrst two words of data are set to zero before any calls are made to filter. If data 
is NIL and filter references data, the signal NiiData should be raised. 

69.2.8 Signals and Errors 

SyntaxError: signal [r: xstring.Reader]; 

The resumable signal SyntaxError can be raised if incorrect syntax is encountered by 
Boolean, Decimal, Number, or Octal. In each case, resuming the signal causes the 
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procedure to return a default value (described in the discussion of the various procedures). 
The reader parameter is the token collected that has the wrong syntax. 

NilData: signal; 

Procedures that take a FtlterProcType argument also take an argument that is a pointer to 
client instance data. If the client has no need for instance data, it can pass a nil as the 
instance data pointer. If a FiiterProcType attempts to access the client-instance data, but 
the client passed in nil instead of a pointer to instance data, the signal Nil Data should be 
raised. Implementors of FilterProcTypes are strongly encouraged to check for nil and raise 
this condition if they use client-instance data. 

UnterminatedQuote.'SiGNAL; 

The resumable signal UnterminatedQuote is raised from MaybeQuoted if the getChar 
procedure of the Handle returns xchar.not or xchar.null before the terminating quote 
character has been read. If the signal is resumed, MaybeQuoted will return as if it had 
read a closing-quote character. 

69.2.9 Built-in Filters 

Alphabetic: FiiterProcType; 

Alphabetic defines the class of alphabetic characters; that is, the characters *a through 'z 
and *A through 'Z. This procedure requires no filter state. 

AlphaNumeric: FiiterProcType; 

AlphaNumeric defines the class of alphanumeric characters, that is, the characters 'a 
through 'z, 'A through 'Z, and '0 through '9. This procedure requires no filter state. 

Delimited: FiiterProcType; 

When Delimited is passed to a procedure such as Filtered, the value of skip passed along 
with it must be nonToken. It will skip leading white space, then define the first character 
of the token to be both the opening-quote character and the closing-quote character, 
returning all characters occurring between the first and second appearance of that 
character. 

Line: FiiterProcType; 

Line defines a class containing all characters except the carriage return. It can be used to 
collect a line of information. This procedure requires no filter state. 

NonWhiteSpace: FiiterProcType; 

NonWhiteSpace FiiterProc defines all characters that are not white space; that is, 
WhiteSpace[char] s'-NonWhiteSpacetchar]. This procedure requires no client data (data 
may be nil.) 

Numeric: FiiterProcType; 
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Numeric defines the class of numeric characters (the characters *0 through *9) This 
procedure requires no filter state. 

Switches: FiiterProcType; 

Switches can be used to collect switch characters. It accepts the characters and 
alphanumeric characters. This procedure requires no filter state. 

WhiteSpace: FiiterProcType: 

The WhiteSpace FiiterProcType defines the white space characters. This filter is used by 
Tolcen for skipping white space. This procedure requires no filter state. 

69.2.10 Built-in Quote Procedures 
Brackets: QuoteProcType: 

Bracicets recognizes the following sets of matching open/close quote pairs: (),[],{}, and < 
>, 

Quote: QuoteProcType: 

Quote recognizes single quote and double quote.' 
69.3 Usage/Examples 

69.3.1 Collecting Tokens 

The following example collects name and number pairs from a stream. It uses the built-in 
stream handle provided by XToken for the source of characters. It uses the Item operation. 

ProcessitemsFromStream: procedure [stream: stream.Handle] « { 
tH: xTokert.Handle 4-xToken.lHandleFromStream[stream]; 
name: xstnng.ReaderBody XToken.item[tH]; 
number: long integer; 
UNTIL xstring.Empty[@name] oo 

number 4- XToken.Oecimai[h: tH, signaiOnError: false]; 

Processltem[@name, number]; - do work 

[] 4- XToken.FreeTokenString[@name]; 

name XToken.ltem[tH]; 

ENDLOOP; 

[] 4- XToken.FreeStreaml^andle[tH]}; 

The following example demonstrates how the XToken interface could be used to parse 
input into tokens, optionally followed by switches. In this context, tokens and switches are 
defined to be any sequence of non- white-space characters, not including the slash character 
(/). 

GetToken: procedure returns [token, switches: xstnng.ReaderBody] » 

BEGIN 

get: XToken.GetCharProcType s (RETURN[GetCommandLineChar[]]}; 
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getToken: xToken.Object [getChar: get, break: xchar.notl; 
slash: xchar.Character a V.ORo; 
MyFilter: XToken.FiiterProcType ■ { 
return[select true from 

xToken.WhiteSpace[c, data], c ■ xchar.not ■ > false, 

C ■ slash ■ > FALSE, 
ENDCASE ■ > true]}; 

token 4- XToken.Fiitered[@getToken, nil, MyFilter]; 

IP g«tToken.break ■ slash then switches 4-xok«n.Fiitered[@getToken, nil, MyFilter] 

ELSE switches xstrmg.nullReaderBody; 

end; 

We can extend this example so that the token is defined to be either a sequence of non- 
white-space characters or a sequence of characters, containing white space characters, 
between double quotes. 

GetToken: procedure returns [token, switches: xstring.ReaderBody] » 

BEGIN 

get: xToken.GetCharProcType > {RETURN{GetCommandUneChar[]]}; 
getToken: XToken.Object <- [getChar: get, break: xchar.not]; 
slash: xchar.Character a V.ord; 
doubleQuote: xchar.Character » '".ORo; 
IsQuote: XToken.QuoteProcType » { 

return[1F c ■ doubleQuote then c else XToken.nonQuote]}; 
MyFilter: XToken.FiiterProcType ■ { 

RETURN[SELECT TRUE FROM 

XToken. WhiteSpacelc data], c « xchar.not » > false, 

C ■ slash ■ > FALSE, 
ENDCASE « > TRUE]}; 

token <- xToken.MaybeQuoted[@getToken, nil, MyFilter, isQuote]; 
iFgetToken.break ■ slash THEN Switches <-xoken.Filtered[@getToken, NIL, MyFilter] 
ELSE switches 4- xstring.nullReaderBody; 
end; 
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ButtonlnterchangeDefs 



70.1 Overview 

The ButtonlnterchangeDefs interface enables clients to create and enumerate anchored 
Cusp button frames. Unanchored buttons (those nested within graphic frames) are handled 
by GraphicslnterchangeOefs. The reader should be familiar with OocinterchangeOefs and 
GraphicslnterchangeOefs before reading further. 

70.1.1 Creating a button 

The typical scenario for creating an anchored button in a document is: 

[doc: doc, ...] «- DoclnterchangeDefs.StartCreation[...]; 
[h, buttonProgram] <-StartButton[ 

doc: doc, buttonProps: buttonProps, wantProgramHandle: true); 
GraphicslnterchangeDefs.AppendMumbleToButtonProgram[to: buttonProgram, ...]; 
GraphicslnterchangeDefs.ReleaseButtonProgram[bpPtr: ©buttonProgram]; 
[...] DoclnterchangeDefs.AppendAnchoredFrame[ 

to: doc, type: cuspButton, content: FinishButton(hl, ...J; 
[...] <~DoclnterchangeDefs.FinishCreation[docPtr: @doc, ...]; 

70.2 Interface Items 

StartButton: proc[ 

doc: OoclnterchangeD«fs.DOC, 

buttonProps: 6raphksinterchangeOefs.ReadonlyButtonProps, 
wantProgramHandle: boolean 4- false] 

RETURNS [ 

h: GraphicsinterchangeOefs.Handle, 

buttonProgram: GraphicslnterchangeDefs.ButtOnProgram]; 

This interface is used to begin creation of an anchored button (see 
6raphicsinterchangeOefs.StartButton for nested buttons), doc must have been obtained from 
Oo€inter€hangeOefs.StartCreation (i.e., doc must not be read-only). The name inside of 
buttonProps should either be a valid button name or be NIL, in which case the button will 
assume a default name. wantProgramHandle determines whether the returned 
buttonProgram is valid or nil. Pass true for this if you want a non-NiL program for this 
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button. Use the GraphicsinterehangeDefs.Append*ToButtonProgram interfaces to fill in the 
buttonProgram. If you pass wantProgramHandle = true, you MUST call 
GraphicsinterchangeOefs.ReleaseButtonProgram (before FinishButton -- see below) on the 
returned buttonProgram (after you have done all the appending you want), h is a handle 
you may add graphic objects to. See the CiraphicsinterchangeOefs.Add* interfaces. StartButton 
may raise Oodnt«rchang«o«fs.Error[documentFuil, readonlyOoc, outOfDiskSpace, outOfVM, 
badParameter]. 

FinishButton: PROC [h: 6raphicslnterchang«0efs.Handle] 
RETURNS [button: oocinterchangeOefs.lnstance]; 

Finishes all the non-program aspects of button creation and returns an instance to pass to 
the content parameter of DocinterchangeD«fs.AppendAnchoredFrame. If you passed 
wantProgramHandle = TRUE to StartButton, you must call 
Graphicsinterchangeo«fs.ReleaseButtonProgram (and before calling FinishButton). 

ButtonlnfoForAnchoredFrame: proc [ 

doc: DoclnterchangeOefs.DOC, 
anchoredFrame: oodnterchangeDefs.lnstance, 
props: 6raphi€SlnterchangeOefs.ButtonProps, 
zone: uncounted zone] 

RETURNS [readonly ButtonProgram: GraphicsinterchangeOefs-ButtonProgram]; 

This interface is used to read the name and program of a button during enumeration. To 
enumerate the graphic objects contained in the button, call 
Graphicsint«rchdng«oefs.Enum«rate[..., graphicsContainer: anchoredFrame, ...] 
(anchoredFrame is a parameter passed to a OocinterchangeOefs.AnchoredFrameProc). 
props.name is copied into the zone passed in, so the client is responsible for this storage. 
Use GraphicsinterchangeOefs.EnumerateButtonProgram to enumerate the text in the returned 
readOnlyButtonProgram. The client must call ReleaseReadOnlyButtonProgram to release 
the program after enumerating it. Do not call GraphicsinterchangeOefs.ReleaseButtonProgram 
on the returned readOnlyButtonProgram - that interface is for releasing client-created 
button programs. 

ReleaseReadOnlyButtonProgram: proc [ 

ptr: LONG pointer TO 6raphicslnterchang«Defs.ButtOnProgram]; 

This must be called each time ButtonlnfoForAnchoredFrame is called. It releases the 
returned readOnlyButtonProgram. This interface should not be called on programs 
obtained from either StartButton or GraphicsinterchangeOefs.StartButton use 
GraphicsinterchangeOefs.ReieaseButtonProgram on those. 
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ButtonlnfoForAnchoredFrame: proc 2 

FinishButton: proc 2 

ReleaseReadOnlyButtonProgram: proc 2 

StartButton: proc 1 
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71.1 Overview 

ChartOatainstaiiDefs provides the ability to install new data in a chart without regard to 
the type of the chart. Specifics such as line styles or shadings are not affected. Typical 
clients include those that have changing data depicted in chart form (one such client is the 
Viewpoint database package). 

71.2 Interface Items 

The primary type in this interface is the Handle, which points to a record of chart 
information. Clients may obtain a handle by either calling GetChartFromlnstance or 
GetChartFromSelection. Once the client has a handle, several functions can be performed 
on the chart; installing new data or validating the chart are some examples. 

Handle: TYPE ■ long pointer to Object; 

Object: type ■ record [ 
type: ChartType, 

I nstance : oocinterchangeoef s.l nstance, 
valldateChart: VaiidateChartProc, 
validateOata: ValidateDataProc, 
plot: PlotProc, 
free: FreeProc]; 

ChartType: type ■ machine dependent {bar(0)« line(1), ple(2), last(15)}; 

type refers to the manner that the chart displays information, instance is a record that has 
pointers to the chart data. vaiidateChart is a call-back procedure to check if the chart can 
be edited. validateOata checks the validity of new data to be installed in the chart, plot 
actually installs the data, while free releases the handle. 

ValidateChartProc: type « PR0c[h: Handle] 
returns [ChartValidity]; 

ChartValidity: type ■ machine dependent {ok(0), ciosed(l), readOniy(2), iast(15)}: 
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VaiidateChartProc checks the chart and returns its status. This procedure should be called 
before any attempt to operate on the chart. 

VaiidateDataProc: type ■ proc[ 
h: Handle, 
data: Data, 
changes: Selections] 
RETURNS [DataVaiidity]; 

DataValidity: TYPE ■ machine dependent record [ 
v(0): SELECT result(0): Data ValidityResult from 

ok ■ > NULL, 

invalidSource ■ > null, 

stzeMismatch « > [extraRows(l): integer, extraCois(2): integer], 
nonNumericValue « > [row(1): cardinal, coi(2): cardinal], 
illegalValue ■ > [row(1): cardinal, coi(2): cardinal], 
unknown « > null, 

last a > NULL, 

endcase]; 

OataValidityResult: type ■ machine dependent { 

ok(0). invalidSource(l), sizeMlsmatch(2), nonNumericValue(3), illegal Value(4), 
unknown(5), iast(1 5)}; 

VaiidateDataProc checks the validity of the new data that the client intends to install. The 
data is hot actually installed in this step, data is a pointer to the current data, changes 
specifies which items are being validated. 

DataValidity indicates the validity of the data and in the case of bad data, some additional 
information, extra Rows is the number of extra rows the new data has relative to the 
chart's current data table. A negative number means the chart currently has more rows 
than the data. extraCols is the analagous number for columns, row and col indicate the 
position of the chart's problem. 

PlotProc: TYPE ■ PROCC 
h: Handle, 
data: Data, 
changes: Selections]; 

Selections: type ■ packed array Values of boolean; 

all: Selections ■ all[true]; 

Values: TYPE ■ {title, data, rowLabels, colLabels, orientation}; 

PlotProc sets the chart's data and then redraws the chart, data is a pointer to the new data 
to be installed, changes specifies exactly which data is set. 

Data: TYPE « long pointer to DataRec; 

DataRec: type ■ record [ 
title: xstring.Reader 4-NiL, 
data: Data Values, 
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rowLabeis: Labels <~nil, 
colLabels: Labels <-niu 
orientation: Orientation row]; 

OataValues: TYPE > long pointer to RowSeq; 

RowSeq:TYPE ■ record [ 

rows: SELECT format: OataFormatFROM 

string ■ > [sequence nRows: cardinal of StrlngRow]« 

numeric ■ > [sequence nRows: cardinal of NumericRow] 
endcase]; 

DataFormat: type ■ {string* numeric}; 
Labels: TYPE ■ long pointer to LabelSeq; 

LabelSeq: type ■ record [sequence length: cardinal of xstring.Reader]; 
Orientation: type « {column, row}; 

DataRec contains the data to be Installed, title is the title of the chart, data points to a 
sequence-containing record of data values. rowLabels and colLabels point to sequence- 
containing records of row and column labels, respectively, orientation specifies whether 
columns or rows are the chart's data sets. 

StringRow: TYPE ■ long pointer to StringRowElements; 

StringRowEIements: type > record [sequence nCols: cardinal of xstring.Reader]; 

NumericRow: type ■ long pointer to NumericRowElements; 
NumericRowElements: type « record [sequence nCols: cardinal of XLReai.Number]; 

StringRow points to a sequence-containing record of readers; similarly, NumericRow 
points to a sequence-containing record of numbers. 

Hence, the data to be installed looks like Figure 71.1: 

GetChartFromlnstance: proc [Instance: DocinterchangttDefs.Instance] 
RETURNS [Handle]; 

This procedure returns a handle to the chart given by instance. The result will be nil if the 
instance is not a chart. Note that a non-NiL handle doesn't guarantee that the chart is valid; 
it only guarantees that the instance is a chart. Clients should call the chart's 
vaiidateChartProc to determine the chart's validity. 

GetChartFromSelection: proc returns [Handle]; 

This procedure obtains a handle by converting the current selection. If the current 
selection is not a chart, nil will be returned. 

FreeProc: type « PROc[h: Handle]; 

FreeProc frees the handle passed in by GetChartFromSelection or 
GetChartFromlnstance. 
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Figure 71.1 



OutOfRoomForGraphics: error; 



Raised by handle.plot if there is no more room in the document to insert graphic objects 
(the components of charts). 



71.3 Usage 

The typical pattern of use for this module is: 



liandle «- GetChartFromSelection(]; 
IF handle # nil then { 
DO 

< < get raw datB; > > 

IF handle.validateChart[handle] # ok then {<<errof;>> loop}; 

< < determine which pieces of data are to be changed > > 

< < allocate and fillin data record> > 

IF handle. valldateDatathandie, data, selections] # ok then < < error; > > 
handle.plot[handie, data, selections); 

ENDLOOP; 

handle.free[handlel; 
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72.1 Overview 

The OodnterchangeOefs interface enables clients to create a new VIewPoint document or 
read an existing one. However, it does not support inserting new information or changing 
or deleting the contents of a document. 

OodnterchangeOefs provides procedures to create or read any of the basil: document 
structures, such as text; textual '^tiles;" fields; headings and footings; or frames of various 
types. It does not include procedures to manipulate contents of frames, however. 

To create content within frames, the client must use interfaces specific to a particular 
frame type. The following interfaces are currently available: 

Graphics! nterchangeOefs for creating or reading graphics frames 

TabieinterchangeDef s for creating or reading tables 

TextlnterchangeOef s for creating or reading text frames 

EquationlnterchangeOef s for creating or reading equation frames 

ButtonlnterchangeOefs for creating or reading anchored button frames 

These are currently the only frame content interfaces available. 

72.1.1 Creating Documents 

To create a ViewPoint document, the first step is to call the procedure StartCreatlon. This 
sets up the data structures for the document and returns a Doc, which is a long pointer to 
an opaque type that represents the document. 

The next step is to add information to the document with various Append* procedures: 
AppendAnchoredFrame, AppendAnchoredFrameX, AppendBreak, AppendChar, 
AppendColumnBreak, AppendField, AppendNewParagraph, AppendPageBreak, 
AppendPFC (Page Format Character), AppendText, or AppendTiie. 

With AppendAnchoredFrame, the client would typically call an operation in an interface 
such as GraphicslnterchangeDefs, or TablelnterchangeDefs to create the contents of the 
frame, and then call AppendAnchoredFrame to add that frame and its contents to the 
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document. With TextlnterchangeDefs, the client calls AppendAnchoredFrame first and 
then uses TextlnterchangeDefs to append information to the text frame, 

AppendFieid, AppendPFC, and AppendTile all have return values: this allows the client to 
call Append* routines recursively to add text and formatting information to fields, tiles, or 
PFC headers. 



When the document contains all the desired information, the client should call 
FinishCreation, which returns an NSFile.Handle for the newly created file. 



72.1.2 Enumerating documents 

To enumerate the contents of an existing ViewPoint document, the client should start by 
calling Open, which opens the document and returns a Doc handle for that document. The 
next step is to call Enumerate, passing in the Doc and an EnumProcs record. The 
EnumProcs record contains a set of callback procedures, one for each of the following 
structures: anchored frame, column break, field, new paragraph, page break, page format 
character, text, tile, or break character (this last via sparel Proc). 

Enumerate proceeds sequentially from the beginning of the document: as it comes to 
different structures within the document, it calls the appropriate callback procedure, 
which handles it appropriately. Each of these procedures returns a boolean value stop; if 
any one of the procedures returns stop = true, the enumeration will terminate. If stop is 
never TRUE, the enumeration will continue to the end of the document. 

Note that the enumeration proceeds according to the ''main flow" of text within a 
document-the text sequence that contains page format characters and frame anchor 
characters. This means that an AnchoredFrameProc will be called not when the frame 
itself is reached, but rather when the frame's anchor character is reached. 
DocInterchangeDefs knows nothing about how the document has been arranged 
structurally by operations such as pagination. As a consequence of this, the enumeration 
can never know what page it is on. 

When the enumeration is complete, the client should call Close to free all associated data 
structures and close any open file handles to the document. 

Note that Creation and Enumeration are totally separate activities and 
procedures/handles associated with one should not be used with the other. Enumeration is 
a readonly operation; no editing should be attempted while it is in progress (the results are 
undefined). Likewise, Enumeration should not be attempted during Creation, 
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72.2.1 Datatypes 

The basic data structure of DocInterchangeDefs is the TextContainer, which is any object 
that can contain text. A TextContainer can be a caption, document, field, heading, footing, 
or spare (spares are for future compatability). 

TextContainer: TYPE » record [ 
var: select type: * from 
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caption ■ > [h: Caption], 
doc ■ > [h: Docl, 
field « > [h: Fieldl. 
heading a > [h: Heading], 
footing ■ > [h: Footing], 
sparel ■ > [h: SpareTC], 
spare2 a > [h: SpareTC], 
spare3 ■ > [h: SpareTC], 
spare4 « > [h: SpareTC], 
endcase]; 

Caption: TYPE > long pointer to CaptionObject; 
CaptionObject: type; 

Doc: TYPE a LONG POINTER TO OOCObject; 

DocObject: type; 

Field: TYPE a long pointer to FieldObject; 
FieidObject: type; 

Heading: type a long pointer TO HeadingObject; 
HeadingObject: type; 

Footing: TYPE a long pointer to FootingObject; 
FootingObject: type; 

Tile: TYPE a long POINTER TO TileObject; 
TiieObject: type; 

SpareTC: type a long unspecified; 
Instance: type[2]; 

instanceNll: instance ■ loophole[long[0]]; 

Note that TextContainers must contain at least one newParagraph character, since the 
paragraph properties of any text are always inherited from the preceding newParagraph 
character. The Doclnterchange implementation supplies the initial newParagraph 
characters as required; the client may assume they already exist. (The client is free to 
append them anyway. The implementation ensures that if the client appends one at the 
start of the TextContainer, two won't appear. The client's paragraph and font properties on 
the newParagraph they appended will have precedence.) 

An Instance is a handle to one of a certain class of objects within a document. Many, 
though not all, objects within a document can be uniquely identified and accessed via an 
Instance. In general, instances form the bridge between OoclnterchangeDefs and the 
frame-content speciHc Interchange interfaces such as GraphicslnterchangeDefs and 
TablelnterchangeDefs: OoclnterchangeDefs will provide an instance which may be passed 
to operations in other Interchange interfaces. No object in any document may be accessed 
through instanceNil. 
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72.2.2 Creating documents 

72.2.2.1 Initializing a document 

The client calls StartCreation to initiate the document creation process. 

StartCreation: proc[ 

paginateOption: PaginateOption 4- compress, 
wantHeadingHandles, wantFootingHandles: bool4- false, 
initialFontProps: Oocint«rdiang«PropsO«fs.ReadonlyFontProps 
initialParaProps: oodntarchangePropso«fs.ReadoniyParaProps ^nil, 
initialPageProps: 0ocint«rchangeProps0efs.ReadoniyPageProps 

RETURNS [ 

doc: Doc, 

leftHeading, rightHeading: Heading* 
leftFooting, rightFooting: Footing, 
status: StartCreationStatus]; 

PaginateOption: TYPE ■ machine dependent { 

none(O), simple, compress, f irstAvailable, lastAvailabie(255)}; 

paginateOption specifies the type of pagination that will occur when the client calls 
FinishCreation. It is specified here rather than in FinisliCreation to enable performance 
optimizations based on the type of pagination that will eventually occur. 

compress pagination provides all the outward signs of pagination, such as page format 
properties, and leaves the structure of the document in its optimized (most compact) 
form. 



simple pagination provides the outward signs of pagination but does not leave the 
document in its optimized form, so subsequent editing may be slower than with 
compress pagination, simple pagination is somewhat faster than compress. 

none leaves the document in its raw form. This can lead to very slow editing, and 
potentially to loss of data. If the document will be more than a few pages long, client 
must specify a paginateOption other than none to avoid losing data. 

wantHeadingHandles and wantFootingHandles specify whether the first page format 
character in the document will have headings and footings. 

initialFontProcs, initiaiParaProcs, and InitialPageProps specify the initial properties for the 
document. If you do not specify a field of initial properties, StartCreation will use the 
document default properties. (For information on document default properties, see the 
DocInterchangePropsDefs chapter) 

In the pageProps, the client must ensure that the page margins leave at least one inch (72 
points) for text. That is, (left margin + right margin + 72 <= page width), and (top 
margin + bottom margin + 72 < = page height). 

StartCreation returns a Doc handle, handles for headings and footings, and a status. The 
Doc handle represents the new document. The client should pass this handle to the 
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Append* procedures described below to add information to the document, and then 
eventually release the handle with a call to FinishCreation. 

If the client releases the handle without ever calling any Append"* routines, the file will 
contain a 1-page document containing a single newParagraph and pageFormat character, 
with the initial font, paragraph, and page props as specified. 

The heading and footing handles that are returned will be nil unless the client specified 
wantHeadingHandies or wantFootingHandles = true. If the headings or footings are 
valid, the client should call various Append"* routines to add text and formatting 
information, and then later release each handle with a call to ReieaseHeading or 
ReieaseFooting. See section 72.2.2.3 for details. 

StartCreation (and all subsequent editing operations on the Doc) may be called either 
normally or by a forked process running in the background. Note that while background 
creation is allowed, the client may have only one process accessing a particular document 
at a time. If forked Creation is desired, the client must call StartCreation in a process that 
is running at Process, priority Background. StartCreation must do special things to be able 
to run in a forked process, and it detects this situation by examining the calling process' 
priority. The client may change the priority once StartCreation returns, if desired. All 
creation operations execute normally in a forked process, although the client must make a 
special call following FinishCreation. See section 72.2.2.4. 

StartCreationStatus: TYPE * machine dependent { 

ok(0), notEnoughOiskSpace, notEnoughVM, firstAvailable, lastAvaiiabie(255)}; 

StartCreation returns a status code, which can have any of the following values: 

ok Everything was fine. 

notEnoughDisi<Space There isn't enough disk space to perform the operation. 
notEnoughVM There isn't enough contiguous virtual memory to create. 

72.2.2.2 Adding to a document 

The Append* routines below add various kinds of information to TextContainers. 

AppendChar, AppendFieid, AppendNewParagraph, AppendText, and AppendTlle take a 
TextContainer as a parameter and add the specified information to that container. The 
remaining procedures (AppendAnchoredFrame, AppendAnchoredFrameX, AppendBreak, 
AppendCoiumnBreak, AppendPFC, AppendPageBreak) take only a Doc, and not a general 
purpose TextContainer; other TextContainers cannot contain the various special 
characters. 

With all of these procedures, the client must manage the storage for the property records or 
other data structures passed in, except for handles obtained from the interface itself. The 
storage for the properties must remain valid during the call to Append*; after Append* 
returns, the client may do anything it chooses with the storage (t3rpically, free it). 
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The Append* procedures often allow the client to set font, paragraph, or page properties. 
Defaulting any of these arguments will cause the newly appended text or object to inherit 
the properties of the preceding text/object and not the application- wide default properties. 

If an Append* routine returns a non-NiL handle, the client is responsible for later freeing 
that handle with a call to an appropriate Release* routine. See section 72.2.2.3 for details. 

AppendAnchoredFrame: proc[ 
to: Oocr 

type: AnchoredFrameType, 

anchoredFrameProps: oocinterchangePropsO«fs.ReadoniyFrameProps, 
content: instance <— instanceNil, 
wantTopCaptionHandle, wantBottomCaptionHandle, 
wantteftCaptionHandie, wantRightCaptionHandle: book-false, 
anchorFontProps: Dodnterchang«Prop$oefs.ReadonlyFontProps nil] 

RETURNS [ 

anchoredFrame: Instance, 
topCaption, bottomCaption, 
leftCaption, rightCaption: Caption]; 

AppendAnchoredFrame appends the anchored frame type with properties 
anchoredFrameProps to the document Doc. 

AnchoredFrameType: TYPE > machine dependent { 

nil(O), bitmap, cuspButton, equation, graphics, IMG, table, text, 
illustrator, firstAvailable, lastAvailable(255)}; 

content is the contents of the frame. Currently, there are interfaces to support creating 
graphics, table, text, equation, and button frames. 

want*CaptionHandle specifies which captions the frame should have. anchorFontProps 
specifies the font properties of the frame anchor. Changing the font properties of the 
anchor does not affect how that anchor appears on the display, but does affect the default 
properties that succeeding characters will inherit. 

AppendAnchoredFrame returns handles to the frame and its captions. The caption 
handles will be non-NiL only if the client specified true for the corresponding 
want*CaptionHandle parameter. The client must later release each valid caption handle 
with ReleaseCaption. 

The return parameter anchoredFrame is currently used only by the TextinterchangeOefs 
interface for appending text frames. 

AppendAnchoredFrameX: proc [ 
to: Doc, 

type: AnchoredFrameType, 

anchoredFrameProps: DocinterchangePropsD«fs.ReadonlyFrameProps, 
content: Instance <-instanceNil, 
wantTopCaptionHandle, wantBottomCaptionHandle, 
wantLeftCaptionHandle, wantRightCaptionHandle: bool^false, 
anchorFontProps: DocinterchangePropsOefs.ReadonlyFontProps nil] 
returns [ 
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anchoredFrame: Instance, 
topCaption, bottomCaption, 
leftCaption, rightCaption: Caption]; 

This operation is similar to AppendAnchoredFrame, except table frames are handled a bit 
differently. For these, whatever frame size is specified in the anchoredFrameProps will be 
used without modification. The normal AppendAnchoredFrame ignores the frame size 
passed in for tables and always creates the a table frame that just fits around the enclosed 
table. (In the next major release the original AppendAnchoredFrame should function as 
this does, and the extra interface will go away.) This operation is currently defined in 
DodnterchangeExtraSDefs. 

BreakProps: TYPE ■ long pointer to BreakPropsRecord ; 
ReadonlyBreakProps: TYPE ■ long pointer TO readonly BreakPropsRecord; 
BreakPropsRecord: TYPE « record [ 

breakType: BreakType, 

sparel : long cardinal]; 

BreakType: type » machine dependent { 

newPage(O), newLeftPage, newRightPage, newColumn, firstAvailable, 
lastAvailabie(255)}; 

AppendBreak: proc ( 
to: TextContainer, 
breakProps: ReadonlyBreakProps, 

fontProps: Oo<interchangePropsDefs.ReadonlyFontProps «-nil]; 

AppendBreak appends a break character to the document. fontProps are the properties of 
the break character; these properties do not affect the appearance of the character itself, 
but they do affect the properties that succeeding characters will inherit. This operation 
and its associated types are currently defined in DoclnterchangeExtral Defs. 
AppendBreak replaces AppendColumnBreak and AppendPageBreak, which are obsolete 
(though still supported). 

AppendChar: proc[ 
to: TextContainer, 
char: xchar.Character, 

fontProps: Oo<lnterchangePropsDefs.ReadonlyFontPropS 4- NIL, 

nloAppend: cardinal <- 1]; 

AppendChar appends one or more copies of the text character char to the specified 
TextContalner. nToAppend speciHes the number of copies of the character that are to be 
appended; fontProps specifies the character properties. 

AppendColumnBreak: proc[ 

to: Doc, fontProps: DodnterchangeProp$oef$.Readoniy FontProps nil]; 

AppendColumnBreak appends a column break character to a document. fontProps are the 
properties of the column break character; these properties do not affect the appearance of 
the character itself, but they do affect the properties that succeeding characters will 
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inherit. Note: this operation is obsolete, but still supported. We recommend using 
AppendBreak instead. 

AppendFieid: proc[ 

to: TextContainer, . 

fieldProps:oocint«rchangePropsOefs.ReadonlyFteidProps, 
fontProps: DodnterchangePropsOefs.ReadonlyFontProps nil] 
RETURNS [field: Field]; 

AppendFieid appends a field to the specified TexKontainer. AppendFieid returns a field; 
the client can then add information to the field by using the Field as the TextContainer in 
other calls to Append* routines (but not AppendFieid again.) When the client is through 
with the field, it must release it via ReleaseField. See section 72.2.2.3. 

Note that the client cannot set the fill-in order of the fields when they are appended to the 
document. This may be done via AppendltemToFiillnOrder, which is described in section 
72.2.5. 

AppendNewParagraph: proc[ 
to: TextContainer, 

paraProps: oocinter<:hangePropso«f$.ReadoniyParaProps <-NiL, 
fontProps: DoclnterchangePropsDefs.ReadonlyFontPropS *- NIL, 

nloAppend : cardinal *-^]; 

AppendNewParagraph appends one or more new paragraph characters to a TextContainer 
object. nToAppend specifies the number of characters to be appended. paraProps and 
fontProps specify the properties for the paragraph. If paraProps is nil, the new paragraph 
inherits the props of the previous paragraph; otherwise, paraProps determines the 
properties of the paragraph. 

Note that TextContainers always contain at least one newParagraph character. The client 
does not have to provides these initial newParagraph characters; Doclnterchange 
implementation supplies them as required, (see the end of section 72.2. 1) 

AppendPageBrealc: PR0C[ 

to: Doc, fontProps : 0o€interchangeProps0efs.Readonly FontProps nil] ; 

AppendPageBrealc appends a page break character to the text of a document. The 
fontProps do not affect the appearance of the page break character itself, but they do affect 
the properties that succeeding characters will inherit. Note: this operation is obsolete, but 
still supported. We recommend using AppendBreak instead. 

AppendPFC: proc [ 
to: Doc, 

pageProps: oocinterchangePropsoefs.ReadoniyPageProps, 
wantHeadingHandles, wantFootingHandles: bool^-false, 
fontProps: DocinterchangePropsOefs.Readonly FontProps 4- nil] 

RETURNS [ 

leftHeading, rightHeading: Heading, 
leftFooting, rightFooting: Footing]; 
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AppendPFC appends a page format character to the main document text. 

pageProps specify the properties for the new page. The client must ensure that the page 
margins leave at least one inch (72 points) for text. That is, (left margin * right margin * 72 
< ■ page width), and (top margin * bottom margin 72 < ■ page height). 

The heading and footing handles that are returned will be nil unless the client specified 
wantHeadingHandlesorwantFootingHandles s true. 

If the heading and footing handles are valid, the client can then use them as 
TextContainers for further calls with Append* procedures. If the headers are to be the 
same on left and right pages, only leftHeading need contain the heading; rightHeading 
should be nil. The same rule applies for leftFooting and rightFooting. 

When creating a heading or footing, the client should note that there are no automatic 
positioning parameters for information in headers and footers; the client must call the 
appropriate Append* procedures to add the desired text and position it with standard text 
formatting, such as white-space characters, paragraph alignment, leading, line height, and 
tabs. 

Additionally, there is no page number pattern; the client must place any surrounding text 
directly in the heading/footing text, inserting the # character at the position(s) where a 
page number is desired. (Note that there is a procedure, 
DocinterchangePropsD«fs.GetPageNumberOelimiter, that returns this character.) 

The client must later free every non-NiL heading or footing with a call to ReleaseHeading or 
ReleaseFooting. 

AppendText: proc [ 
to: TextContainer, 
text: xstring.Reader, 
textEndContext: xstn'ng.Context, 

fontProps: DocinterchangePropsOefs.ReadonlyFontProps <-nil]; 

AppendText appends the text with the specified properties to the TextContainer. For 
efficiency, the client should pass the appropriate textEndContext if it is known (just like 
xstring.AppendReader). text may not contain newParagraph characters ([set: 0, code: 
35B]). Use AppendNewParagraph to append these. 

AppendTile: PROc( 
to: TextContainer, 
type: Atom.ATOM, 

data: long pointer nil, 

fontProps: Do<interchangeProp$Oefs.ReadonlyFontProps ^nil] 
RETURNS [tiie: Tiie]; 

AppendTile is for future use. The tile type and data format are defined elsewhere, agreed 
upon by parties on either side of this interface. 
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72.2.2.3 Releasing storage 

ReleaseCaption: proc [captionPtr: long pointer to Caption]; 
ReleaseFteld: proc [f ieldPtr: long pointer to Field]; 
ReleaseHeading: proc [headingPtr: long pointer to Heading]; 
ReleaseFooting: PROc[footingPtr: long pointer to Footing]; 
ReleaseTiie: proc [tilePtr: long pointer to Tile]; 
ReleaseSparel : proc [ptr: long pointer to SpareTC]; 
ReieaseSpareZ: proc [ptr: long pointer to SpareTC]; 
ReleaseSpare3: proc [ptr: long pointer to SpareTC]; 
ReleaseSpare4: proc [ptr: long pointer to SpareTC]; 

The client must call ReleaseCaption, ReleaseField, ReleaseFooting, ReleaseHeading, 
ReleaseTiie. or ReleaseSpare to release resources associated with- any non-NiL handle 
obtained from any Append"* procedure. 

After calling Release*, the handle will be invalid. To help prevent use of an invalid handle, 
the Release* routines take a pointer to the handle, and set the handle itself to nil. (This is 
similar to Mesa's free operation.) 

72.2.2.4 Finalizing a document 

FinishCreation: PROC[ 

docPtr: long pointer to Doc, 
checkAbortProc: CheckAbortProc <-nil, 
checkAbortClientData: long pointer 4-nil] 
returns! 

docFile: NSFite.Handle, 

session: NSFtio.Session, 

status: FinishCreationStatus]; 

When the document is complete, the client must call FinishCreation to finalize the 
document and release the Doc handle. FinishCreation returns an NSFile.Handle to the 
newly-created document, an NSFile.Session, and a status. The file handle is valid in the 
returned NSFile session. The session returned will be the default session if the client 
called FinishCreation normally (not by a forked background process). If StartCreation was 
called by a forked background process, then the returned session will be a private session 
created by StartCreation. The client must kill this private session by calling 
NSFile.Logoff[session] after it's finished processing the document file. The document that 
FinishCreation provides will be in paginated form if the client so specified in StartCreation. 

CheckAbortProc: type a PR0C[ciientData: long pointer] returns [abort: bool]; 
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If the client specified a checkAbortProc, then a call-back procedure will be invoked before 
the call to FinishCreation returns; this call-back can abort the document's completion. 
checkAbortCiientData is a client defined argument and is passed into the call-back 
procedure. 

FtnishCreationStatus: TYPE ■ MACHINE DEPENDENT {ok(OK 

aborted, okButNotEnoughDiskSpaceToPaginate, okBuNotEnoughVMToPaginate, 
okButUnknownPaginateProbiemr f irstAvaiiabie, iastAvailable(255)}; 

FinishCreation also returns a status code, which can have any of the following values: 

aborted do not complete the document. 

okButNotEnoughOiskSpaceToPaginate, 
okBuNotEnoughViy/IToPaginate, 

okButUnknownPaginateProbiem the document is finished but left unpaginated 

This document file is temporary, and will be purged from the NSFile system if a rerboot 
occurs before it is made permanent. To make the file permanent, the client should call 
move it to the current user desktop with NSFiie.Move, followed by a call to 
StarOesktop. Add Reference to put the icon on the display. (See section 72.3 for an example of 
this.) 

AbortCreation : proc [docPtr: long pointer to Ooc]; 

AbortCreation aborts document creation and deallocates the storage associated with that 
document. AbortCreation will kill the private session if StartCreation was called by a 
background process, so the client should not call NSFiie.Logoff[session] after having called 
AbortCreation. 

72.2.2.5 Utilities 

The following procedures are utilities that may be of use to the client creating a document. 

GetModeProps: proc [doc: Doc, modeProps: OQcinterchang«PropsOefs.ModeProps]; 

SetModeProps: proc[ 
~ doc: Doc, 

modeProps: oocinterchangePropsOefs.Readonlyl\/lodeProps, 
selections: OoclnterchangePropsOefs.lVlodeSeiections]; 

Get or set the mode properties for the document; these procedures may be called at any 
time. When setting mode properties, only those properties designated by true selections 
will be changed. 

SetCurrentParagraphProps: proc[ 
textContainer: TextContainer, 
paraProps: oocinterchangePropsOefs.ReadonlyParaProps]; 

SetCurrentParagraphProps can be called at any time, such as in the middle of a paragraph 
or (even if it makes no sense) repeatedly with different properties. If it is called repeatedly 
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in the same paragraph, only the most recent call will remain in effect. The client can call 
this procedure on any TextContainer, including a document. 

SetCurrentParagraphProps affects the entire current paragraph, including any portion not 
yet appended at the time it is called. The properties also affect all subsequent paragraphs 
unless the client overrides the properties with new ones passed to AppendNewParagraph, 
or by another call to SetCurrentPiaragraphProps. 

Note, however, that setting paragraph properties on a TextContainer will cause an error if 
that TextContainer does not contain any paragraph characters. Although Ooclnterchange 
does guarantee that every TextContainer will contain at least one new paragraph 
character, those paragraph characters are added (if necessary) during the Append* 
routines. Thus, calling SetCurrentParagraphProps before calling any Append* routines 
will cause an error. To avoid this problem, the client can simply call AddNewParagraph to 
ensure that the TextContainer does have a paragraph character. Since the Append* 
routines only add a new paragraph if necessary, this will not cause duplication. 

72.2.3 Enumerating documents 

72.2.3.1 Open 

Open:PROc[ 

docFileRef : NSFJie.Reference, 
session: NSFiie.Session 4-NSFii«.nullSession, 
password: xstring.Reader <— nil] 
RETURNS [doc: Ooc, status: OpenStatus]; 

To enumerate a document, the first step is to call Open. Open takes a NSFile.Ref erence for a 
file and opens it for reading in the NSFiling session specified by the session argument. The 
client should then pass Doc returned to Enumerate, which will parse the document. Open 
(and all subsequent reading operations on the Doc) may be called either normally or by a 
forked process nmning in the background. Note that while background enumeration is 
allowed, the client may have only one process accessing a particular document at a time. 
All reading operations execute normally in a forked process. If session is defaulted, 
NSFIIe.GetOefaultSessionQ will be used. 

password is provided in anticipation of future password-locking of documents, password is 
currently ignored. 

OpenStatus: TYPE ■ machine dependent { 

ok(0), malFormed, incompatible, notLocai, outOf DiskSpace, outOfVM, busy, 
invalidPassword, firstAvailable, lastAvailable(255)}; 

Open also returns a status code, which can have any of the following values: 

ok Everything was fine 

malFormed The Document is inconsistent internally. 

incompatible The document is of a version that the VP Document Editor cannot 

open. 
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notLocai 



The document is not on the workstation, so it cannot be opened. 



outOfDiskSpace 



There isn't enough disk space to open the document. 



outOfVM 



There isn't enough contiguous virtual memory. 



busy 



Another process is using the file (e.g. background pagination). 



invaiidPassword 



The user does not have the credentials to open the document. 



72.2.3.2 Enumerate 



Enumerate: PROC[ 

textContainer: TextContainer, 
procs: EnumProcs, 
clientData: long pointer nil] 
RETURNS tdataSkipped: bool]; 

Enumerate parses the contents of the specified TextContainer. The client may pass a nil 
value as the textContainer-that call to Enumerate will do nothing, (nil textContainers 
may be passed to the client; the client need not check for nil before attempting to 
enumerate one. This does not imply, however that non-NiL textContainers have any 
content-they may be empty yet have a non-NiL handle.) 

procs is a record that contains client-defined callback procedures to enumerate the various 
kinds of structures that can be found in a TextContainer. 

dataSkipped will be true if Enumerate encountered an object that it didn't recognize, or if it 
encountered an object for which a client call-back procedure was not supplied. 

EnumProcs: TYPE ■ long pointer TO EnumProcsRecord; 

EnumProcsRecord: type ■ record ( 

anchoredFrameProc: AnchoredFrameProc <-nil, 
coiumnBreakProc: CotumnBreakProc <~nil, 
fieidProc: FieldProc4-NiL, 
newParagraphProc: NewParagraphProc <-NiL, 
pageBreakProc: PageBreakProc ^nil, 
pfcProc: PFCProc<-NiL, 
textProc: TextProc <- nil, 
tileProc: TileProc<-NiL, 
sparelProc: SpareProc <-nil, 
spare2Proc: SpareProc <-nil, 
spareSProc: SpareProc <- nil, 
spare4Proc: SpareProc^ nil]; 

Each of the procedures in an EnumProcsRecord takes as parameters the properties of the 
structure and its content when appropriate. Note that the storage for the properties passed 
to these procedures is temporary; the client must explicitly copy any properties it wishes to 
save. For a description of the various properties, see the corresponding Append* routines. 

sparelProc, if not nil, will be called for all break characters. Its data parameter should be 
LOOPHOLEd into a ReadonlyBreakPropsForEnum (currently defined in 
DocinterchangeExtralDefs). coiumnBreakProc and pageBreakProc are obsolete, but still 
supported. If sparelProc is not nil, then both coiumnBreakProc and pageBreakProc must 
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be. Conversely, if either columnBreakProc or pageBreakProc is not nil, then sparelProc ^^^^ 
must be. We recommend using sparelProc for enumerating break characters, as it is more ' 
robust. 

AnchoredFrameProc: type ■ proc [ 
clientData: LONGPOiNTERr 
type: AnchoredFrameType, 

anchorFontProps : oocint«rchang«Propso«f s.Readoniy FontProps, 
anchoredFrame: instance, 

anchoredFrameProps: DocinterchangePropso«fs.ReadoniyFrameProps, 

content: Instance, 

topCaption, 

bottomCaption, 

leftCaption, 
rightCaption: Caption] 

RETURNS [stop: BOOL FALSE]; 

ColumnBreakProc: type « proc [ 
ciientData: long pointer, 

fontProps: DocinterchangePropsDefs.ReadonlyFontProps] 
RETURNS [stop: BOOL 4- FALSE]; 

FleldProc: type ■ proc [ 
ciientData: LONG POINTER, 

fontProps: OocinterchangePropsOefs.ReadonlyFontProps, 
fieldProps: DoclnterchangePropsOefs.ReadonlyFieldProps, 

field: Field] 

RETURNS [stop: BOOL ^ FALSE]; 

NewParagraphProc: TYPE ■ PROC [ 
ciientData: long pointer, 

fontProps : DocinterchangePropsOefs.Readonly FontProps, 
paraProps : DocinterchangePropsOefs.ReadoniyParaProps] 

RETURNS [stop: BOOL 4- FALSE]; 

PageBreakProc: TYPE a PROC [ 
ciientData: long pointer, 

fontProps: Do<:lnterchangePropsOefs.ReadonlyFontProps] 

RETURNS [stop: BOOL 4- FALSE]; 

PFCProc: type « proc [ 

ciientData: long pointer, 

fontProps : OodnterchangePropsOefs.Readonly FontProps, 
pageProps: DocinterchangePropsDefs.ReadonlyPageProps, 
leftHeading, rightHeading: Heading, . 
leftFooting, rightFooting: Footing] 

RETURNS [stop: BOOL 4- FALSE]; 

In a PFCProc, if the headers are the same on left and right pages, only leftHeading will 
contain the heading; rightHeading will be nil. (Of course, leftHeading can be nil if it has no jimi^ 
content.) The same rule applies for leftFooting and rightFooting. 
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TextProc: type ■ procI 

clientOata: long pointer, 

fontProps: OocinterchangePropsOefs.ReadoniyFontProps, 

text: xstring.Reader, 
textEndContext: xstring.Context] 

RETURNS [stop: BOOL *- FALSE]; 

In a TextProc, textEndContext will always be accurate; it will never be 
xstring.unknownContext. 

TileProc: type ■ proc [ 

clientOata: long pointer, 

fontProps: Do<inter<hangeProp$Oefs.ReadoniyFontProps, 
type: Atom.ATOM, 

data: long pointer, 
tile: Tile] 

RETURNS [stop: BOOL 4- FALSE]; 

SpareProc: type ■ proc [ 
clientOata: LONG POINTER, 
data: LONGUNSPEaFiEo] 

RETURNS [stop: BOOL <~ FALSE]; 

As it encounters an object of a particular type. Enumerate will call the appropriate 
procedure. If the client defaults a particular procedure, Enumerate will ignore any objects 
of that type. 

Each procedure has a stop return parameter; the enumeration will stop if stop ever has the 
value TRUE. Some of the procedures also have a TextContainer handle as a parameter; the 
client can use this TextContainer recursively in other calls to Enumerate to obtain the 
contents of the TextContainer. 

The clientOata pointer passed in to Enumerate is passed to the callback procedures 
invoked by (that call to) Enumerate. (The clientOata may be different at different 
recursion levels, of course.) 

The handle (header, caption, etc.) supplied to the client in the call-back is readonly and is 
valid only during the call-back's invocation; the client is not reponsible for releasing this 
handle. It is possible for such a handle to be nil; a nil handle means that the corresponding 
object has no text content. 

Note that the enumeration does include the initial paragraph (and possible page format 
characters) that every TextContainer has. Thus, when copying a document into a new 
document, the client should be careful to avoid copying the initial paragraph and page 
format characters and then appending some more initial ones, since that would cause 
duplication. 

72.2.3.3 Close 

Close: PROC [docPtr: long pointer to Ooc]; 
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When through with an enumeration, the client should call Close, which releases storage 
associated with the Doc handle and sets the Ooc handle to nil. 

72.2.4 Errors 

Error: error [why: ErrorCode]; 

ErrorCode: TYPE « machine dependent { 

containerFull(O), documentFuii, readoniyOoc, outOf DiskSpace, outOfVM, 
objectlllegailnContainer, badParameter, unimpiemented, firstAvailable, 
lastAvaiiabie(255)}; 

Any of the Append* procedures can raise an error, which can be one of the following types: 

containerFuil there is no more room to append to this container. 

documentFuil * no more room in the document. 

readonlyOoc document opened in ReadOnly mode. 

outOfDiskSpace not enough disk space for the operation. 

outOfVM not enough virtual memory for the operation. 

objectlliegallnContainer attempted to add an object to a container that does not support 

that object t3rpe. 

badParameter one of the arguments specified was invalid in this context. 

unimpiemented this function is not supported. 

Do not call any Interchange operations from within a catch phrase of Error. 

72.2.5 Fill-in Order 

DocInterchangeDefs provides procedures to append, enumerate, and clear the flll-in order 
of fields and tables. 

AppenditemToFilllnOrder: proc[ 
doc: Doc, 

filllnOrderitemName:xstring.Reader, 
itemType: FilllnOrderltemType]; 

doc is the document that contains the field or table. 

f illinOrderitemName is the name of the object being added to the fill-in order. 

FilllnOrderltemType: type ■ machine dependent { 
f ieid(O), table, f irstAvailabie, lastAvailabie(255)}; 

FilllnOrderltemType specifies the type of object that will be added to the flU-in order. 

EnumerateFilllnOrder: proc[ 
doc: Doc, 
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proc: FilllnOrderProc, 
clientData: long pointer nil]; 

FilllnOrderProc: TYPE « proc[ 
clientOata: long pointer, 
filllnOrderltefnName:xstring.Reader, 
itemType: FilllnOrderitemType] 
returns [stop: bool <- false]; 

proc is a call-baclc procedure that is invoked once for each object in the fill-in order. The 
arguments passed into proc include the name of the enumerated object as well as its type. 
The FililnorderProc can return stop — true to halt the enumeration. 

ciientOata is client defined data that is passed to proc. 

ClearFiiilnOrder: proc [doc: Doc]; 

Clear the fill-in order for the entire document. 

72.3 Usage/Examples 

Here is an example of both enumeration and creation. This program adds two commands to 
the Attention Window: "Copy Most of Doc (Forked)" and "Copy Most of Doc (Notifier)". 
When called, these commands check to see if the current selection is a document. If it is, 
then the program enumerates the contents of that document and copies the information 
into a new document. 

DIRECTORY 



DocExample: program imports DoclnterchangeOefs, ... = { 
~ Types 

DICtxtHandle: type = long pointer to DICtxt; 

DICtXt: TYPE = RECORD [ 

sourceDoc, targetDoc: DoclnterchangeOefs.DOC, 
ignoreNewPar, ignorePFC, aborted, error; boolean]; 
<< A DICtxtHandle is passed as clientData to procs called by 
DoclnterchangeDefs.Enumerate. >> 

< < The following types are used to hold copied heading or footing text. > > 
HeadFootText: type = long pointer to Head FootTextRec; 
HeadFootTextRec: type = record ( 

length: cardinal, list: sequence maxLength: cardinal of ChunkRec]; 
ChunkRec: type = record [ 

fontProps: DoclnterchangePropsDefs.FontPropsRecord, 
v: select type: * from 

np = > [paraProps: DoclnterchangePropsDefs.ParaPropsRecord], 
text = > [rb: XString.ReaderBody,textEndContext: XString.Context], 
endcase]; 

~ Constants 
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z: UNCOUNTED ZONE = BWSZone.shortLifetime; 

- Variables 

diEnumProcsRec: DoclnterchangeDefs.EnumProcsRecord «-[ 
anchored FrameProc: Append Anchored FrameToTargetDoc, 
fieldProc: Append Fi el dToTargetDoc, 

newParagraphProc: Append NewParToTargetDoc, pfcProc: AppendPFCToTargetDoc, 
textProc: AppendTextToTargetDoc, sparelProc: Append BreakToTargetDoc]; 
diEnumProcs: DocInterchangeDefs. EnumProcs s ©diEnumProcsRec; 

- Copy contents of current selection to new doc. 

MakeDoc: proc [docFiieRef: NSFile. Reference, background: bool] = { 
nameRB: XString.ReaderBody 

XString.FromSTRINGC'Copying Most of Doc"u true]; 

CallBack: BackgroundProcess.CailBackProc = { 
sourceDoc: DocInterchangeDefs. Doc; 
openStatus: DocInterchangeDefs. OpenStatus; 

« Use a private session when enumerating source doc so tha t user can 't select 

and open the document while we're reading it » 
sourceDocSession: NSFile.Session = 

(IP background then NSFile.Logon[ 

Atom.GetPropC 

Atom.MakeAtom("CurrentUser"Ll, 

Atom.MakeAtom["ldentityHandle"Ll] t .value] 

ELSENSFile.GetDefaultSessionl]); 
finaiStatus quietSuccess; 
[sourceDoc, openStatus] «- 

DoclnterchangeDefs.Open[docFileRef, sourceDocSession]; 
IF OpenStatus = ok then { - source ok, attempt to copy contents. 

targetDoc: DocInterchangeDefs. Doc; 

diCtxt: DICtxt; 

docFile: NSFile.Handle; 

target DocSessi on : NSFi I e.Sessi on ; 

fontProps: DoclnterchangePropsDefs.FontPropsRecord; 

paraProps: DoclnterchangePropsDefs.ParaPropsRecord; 

pageProps: DoclnterchangePropsDefs.PagePropsRecord; 

sourceLeftHeading, sourceRightHeading, 

sourceLeftFooting, sourceRightFooting: HeadFootText; 

targetLeftHeading, targetRightHeading: DocInterchangeDefs. Heading; 

targetLeftFooting, targetRightFooting: DocInterchangeDefs. Footing; 

CheckAbort: DocInterchangeDefs. CheckAbortProc = { 
abort 4- diCtxt. aborted *- BackgroundProcess.UserAbort[]; 
IF abort THEN BackgroundProcess.ResetUserAbort[]; 

}; 

- start of "openStatus s ok" code 

i 

GetlnitialDocProps[ 

docFileRef, sourceDoc, sourceDocSession, ©fontProps, ©paraProps, 

©pageProps, ©sourceLeftHeading, ©sourceRightHeading, 

©sourceLeftFooting, ©sourceRightFooting, z]; 
[targetDoc, targetLeftHeading, targetRightHeading, 

targetLeftFooting, targetRightFooting, ] 
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DoclnterchangeDefs.StartCreationt 
paginateOption: simple, 

wantHeadingHandles: ((sourceLeftHeading # nil) 
OR (sourceRightHeading # nil)), 
wantFootingHandles: ((sourceLeftFooting # nil) 
OR (sourceRightFooting # nil)), 

Initial FontProps: ©fontProps, initial ParaProps: OparaProps, 
initialPageProps: ©pageProps]; 
iFtargetLeftHeadIng # nil then 
CopyHeadFootings[ 

sourceLeftHeading, sourceRightHeading, sourceLeftFooting, 
sourceRightFooting, targetLeftHeading, targetRightHeadIng, 
targetLeftFooti ng, targetRightFooti ng] ; 
FreeHeadFootText[@sourceLeftHeading, z]; 
FreeHeadFootText(@sourceRightHeading, 2]; 
FreeHead FootText(@sourceLeftFooti ng, z] ; 
FreeHeadFootTextt@sourceRightFooting, 2]; 

IF paraProps.tabStops.BASE # nil then z.FREE[@paraProps.tabStops.BASE]; 
IF pageProps.columnWidths # nil then z.FREE[@pageProps.columnWidths]; 
diCtxt [sourceDoc, targetDoc, true, true, false, false]; 
(] «- DoclnterchangeDefs.Enumerate[ 

Tdoclh: sourceDoc]], dlEnumProcs, ©dICtxt]; 
if dlCtxt.error then {fInalStatus <- failure; goto Aborted}; 
if dlCtxt.aborted then {finalStatus <- aborted; goto Aborted}; 
Copy Fi 1 1 i nOrderAndModePropstsourceOoc, targetDoc] ; 
DoclnterchangeDefs.Close[@sourceDoc]; 

[docFile, targetDocSession, ] <- DoclnterchangeDefs.FinishCreation[ 

©targetDoc, CheckAbort]; 
IF not dlCtxt.aborted THEN 

WrapUpFiling[docFileRef, docFile, targetDocSession]; 
IF background then NSFile.Logoff[targetDocSession]; 

EXITS 

Aborted = > { 

DocI nterchange Def s. CI ose [©so u rce Doc] ; 
DoclnterchangeDefs.AbortCreation[@targetDoc]; 

}; 

}; 
} 

ELSE {PostOpenError[openStatus]; finalStatus <- failure; }; 
IF background then { 

NSFile.Logoff[sourceDocSession]; [] 4-Busylcon.MakeUnbusy[docFileRef]; }; 
}; -CallBack 

~ start ofMakeDoc 
IF background then { 

Process.SetPriority[Process.priorityBackground]; 

[] 4- BackgroundProcess.ManageMe[name: ©nameRB, callBackProc: CallBack]; 
} 

ELSE[]<-CallBack[NIL]; 
}; -MakeDoc 

FreeHeadFootText: proc [ 

hf: LONG pointer to Head FootText, zone: uncounted zone] = { 

IF hff # NIL THEN { 

FOR i: CARDINAL IN [0..hf. length) do 
WITH hf Bound: hf.list[i] select from 
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np = > 

IF hfBound.paraProps.tabStops,BASE # nil then 
zone.FREE[@hfBound.paraProps.tabStops.BASE]; 
text = > XString.FreeReaderBytesir: ©hfBound.rb, z: zone]; 

endcase; 

ENDLOOP; 

zone.FREE(hf]; 

}; 

}; " FreeHeadFootText 

CopyFillinOrderAndModeProps: proc [ 

sourceDoc, targetDoc: DoclnterchangeDefs.Doc] = { 
modeProps: DoclnterchangePropsDefs.ModePropsRecord; 
DoclnterchangeDefs.CIearFilllnOrder[targetOoc]; 
OoclnterchangeOefs.EnumerateFiilinOrder[ 

sourceDoc, AddToFilllnOrder, targetDocI; 
DoclnterchangeDefs.GetModeProps(sourceDoc, ©modeProps]; 
DoclnterchangeDefs.SetModeProps[ 

targetDoc, ©modeProps, [ 

structureShowing: true, nonPrintingShowing: true, 
coverSheetShowing: true, promptFields: true]]; 
}; -CopyFillinOrderAndModeProps 

CopyHeadFootings: proc [ 

sourceLeftHeading, sourceRightHeading, sourceLeftFooting, sourceRightFooting: 
HeadFootText, 

targetLeftHeading, targetRightHeading: DoclnterchangeDefs.Heading, 
targetLeftFooting, targetRightFooting: DoclnterchangeDefs. Footing] = { 
targetTC: DoclnterchangeDefs.TextContainer <- (spare 1 [0]]; 

HitNP: DoclnterchangeDefs.NewParagraphProc = { 
DoclnterchangeDefs.AppendNewParagraph{ 

to: targetTC, paraProps: paraProps, fontProps: fontProps]; 
}; -HitNP 

HitText: DoclnterchangeDefs.TextProc s £ 
DoclnterchangeDefs.AppendText( 

to: targetTC, text: text, textEndContext: textEndContext, 
fontProps: fontProps]; 
}; - HitText 

EnumerateHeadFoot: proc [hf: HeadFootText] = { 

IF hf# NIL THEN { 

FOR i : CARDINAL IN [0..hf .length) do 
WITH hfBound: hf(i] select from 
np = > 

[]«-HitNP[ 

clientData: nil, fontProps: ©hfBound.fontProps, 
pa ra Props : @hf Bou nd . para Props] ; 
text = > 

[] HitTextt 

clientData: NIL, fontProps: ©hfBound.fontProps, 
text: ©hfBound. rb, 

textEndContext: hfBound. textEndContext]; 
endcase; 

ENDLOOP; 
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}; 

}; 

~ start of CopyHeadFootings 

targetTC iheading[targetLeftHeading]]; 

EnumerateHeadFootisourceLeftHeading]; 

DocinterchangeOefs.ReieaseHeading[@targetLeftHeading]; 

targetTC [headingftargetRightHeading]]; 

EnumerateHeadFoot(sourceRightHeading]; 

DoclnterchangeOefs.ReleaseHeading[@targetRightHeading]; 

targetTC <~ [footing[targetLeftFooting]]; 

Enu merateHead Foot(sourceLeftFooti ng] ; 

DoclnterchangeDefs.Re!easeFooting[@targetLeftFooting]; 

targetTC [footing[targetRightFooting]]; 

EnumerateHeadFootfsourceRightFooting]; 

DoclnterchangeDefs.ReleaseFooting[@targetRightFooting]; 

}; -CopyHeadFootings 

PostOpenError: proc [status: DoclnterchangeDefs.OpenStatus] = { 
rb: XString.ReaderBody <~ 

SELECT Status FROM 

notLocal = > XString.FromSTRING("notLocal"L, true], 
outOfDiskSpace = > XStrlng.FromSTRING("outOfDiskSpace"L, true], 
outOfVM = > XString.FromSTRING["outOfVM"L.TRU£], 
busy = > XString.FromSTRING["busy"L, trueJ, 
ENDCASE = > XString.nullReaderBody; 

Attention. Post[s: @rbl; 

}; -PostOpenError 

- Copy contents of current selection to new doc. 
MakeOocMenuCmdProc: MenuOata.MenuProc = { 
iFSelection.CanYouConvert(file] then { 

selValue: Selection.Value <- Selection. Convert[file]; 

fileRef: NS File. Reference = LOOPHOLE(selValue. value, long pointer to 

NSFile. Reference! t ; 
IF loophole [item Data, LONG cardinal] = Othen{ 
Selection.Clear[]; 
[] *- Busylcon.MakeBusyffileRef]; 
Process. Oetach[FORK MakeOQc[flleRef, true]]; 
} 

else MakeOoc[fileRef, false]; 
} 

ELSE UserTerminal.BlinkDisplay[]; 
}; - MakeDocMenuCmdProc 

AddToFilllnOrder: DocinterchangeDefs.FilllnOrderProc = { 
targetDoc: DoclnterchangeDefs.Doc = clientData; 
DoclnterchangeDefs.AppendltemToFilllnOrder[ 
targetDoc, filllnOrderltemName, itemType]; 
}; -AddToFilllnOrder 

< < Called when an anchored frame was encountered in the source document. 

Copies the frame and its contents to the target document. > > 
AppendAnchoredFrameToTargetDoc: DoclnterchangeDefs.AnchoredFrameProc = { 

- use other interfaces here 

}; - AppendAnchoredFrameToTargetDoc 
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AppendBreakToTargetDoc: DoclnterchangeDefs.SpareProc = { 
diCtxt: DICtxtHandle = clientData; 

bp: OoclnterchangeExtra1Defs.ReadonlyBreakPropsForEnum = data; 
DocinterchangeExtra 1 Defs.AppendBreak[ 

diCtxt.targetDoc, bp.breakProps, bp.fontProps]; 
}; -AppendBreakToTargetDoc 

AppendFieldToTargetOoc: DocinterchangeOefs-FieldProc s { 
diCtxt: DICtxtHandle = dientOata; 
procs: DocInterchangeDefs. EnumProcsRecord ^[ 

newParagraphProc: Append NewParToNewFieid, 

textProc: AppendTextToNewFieldl; 
newField: DocinterchangeDefs.Field; 

AppendNewParToNewField: DocinterchangeDefs.NewParagraphProc = { 
DoclnterchangeDefs.AppendNewParagraph[ 
[field(h: newFieldlL paraProps, fontProps]}; 

AppendTextToNewFleld: DoclnterchangeDefs.TextProc = { 
DoclnterchangeDefs.AppendTextt 

[field(h: newField]], text, textEnd Context, fontProps]}; 

IF (diCtxt.aborted *- BackgroundProcess.UserAbort[]) then { 
BackgroundProcess.ResetUserAbort(]; RETURN{stop: true]}; 

newField <- DoclnterchangeDefs.AppendField[ 
[doc[h: diCtxt-targetDoc]], fieldProps, fontProps]; 

[1 «- DoclnterchangeDefs.Enumerate([field(h: field]], ©procs]; 

Docl nterchangeDef s. Rel easeFiel d [@newFi eld] ; 

}; ~ AppendFieldToTargetDoc 

AppendNewParToTargetDoc: DocInterchangeDefs. NewParagraphProc = { 
diCtxt: DICtxtHandle = clientData; 
IF diCtxtJgnoreNewPar then diCtxtJgnoreNewPar *- false 

ELSE 

DoclnterchangeDefs.AppendNewParagraph[ 
[doc[h: diCtxt-targetDocJ], paraProps, fontProps]; 
}; - AppendNewParToTargetDoc 

AppendPFCToTargetDoc: Docl nterchangeDef s.PFCProc = £ 
diCtxt: DICtxtHandle = clientData; 
IF diCtxtJgnorePFC then dlCtxt.ignorePFC false 

ELSE { 

targetLeftHeading, targetRightHeading: DocInterchangeDefs. Heading; 
targetLeftFooting, targetRlghtFooting: DoclnterchangeDefs.Footing; 
procs: DocInterchangeDefs. EnumProcsRecord <-[ 
newParagraphProc: HitNP, textProc: HitText]; 
targetTC: DoclnterchangeDefs.TextContainer <- [spare 1 [0]]; 

HitNP: DocInterchangeDefs. NewParagraphProc = { 
DoclnterchangeDefs.AppendNewParagraph[ 

to: targetTC, paraProps: paraProps, fontProps: fontProps]; 
}; - HitNP 

HitText: DoclnterchangeDefs.TextProc = { 
DoclnterchangeDefs.AppendText[ 



72-22 



Viewpoint Programmer's Manual 



72 



to: targetTC, text: text, textEnd Context: textEnd Context, 
fontProps: fontProps]; 
}; -HitText 

[targetLeftHeadIng, targetRightHeading, 

targetLeftFooting, targetRightFooting] 

DoclnterchangeDefs.AppendPFC[ 

to: diCtxt-targetOoc, pageProps: pageProps, 

wantHeadingHandles: ((leftHeading # nil) OR (rightHeading # nil)), 

wantFootingHandles: ((leftFooting # nil) OR (rightFooting # nil)), 

fontProps: fontProps]; 
targetTC [heading(targetLeftHeading]]; 

[] <- DoclnterchangeDefs.Enumerate([heading[leftHeading]], @procs]; 
DoctnterchangeDefs.ReieaseHeading[@targetLeftHeading]; 
targetTC [heading(targetRightHeading]]; 

[] DoclnterchangeDefs.Enumerate([heading{rightHeading]], ©procsj; 
DoclnterchangeOefs.ReleaseHeading[@targetRightHeadingl; 
targetTC <— [footing(targetLeftFooting]]; 

[] <- DoclnterchangeDefs.Enumerate[[footing(leftFooting]], ©procs]; 
DoclnterchangeDef s. Rel easeFooti ng (©target LeftFooti ng] ; 
targetTC [footingftargetRightFooting]]; 

[] DoclnterchangeDefs.Enumerate([footing[rightFooting]], ©procs]; 
DoclnterchangeDefs.ReleaseFooting(@targetRightFooting]; 

}; 

}; - AppendPFCToTargetDoc 

AppendTextToTargetDoc: DoclnterchangeDef s.TextProc = { 
diCtxt: DICtxtHandle = clientData; 

if (diCtxt. aborted <- BackgroundProcess.UserAbortI]) then { 
BackgroundProcess.ResetUserAbortd; RETURN(stop: true]; }; 

DoclnterchangeDefs.AppendTextl 

[doc[h: diCtxt. targetDoc]], text, textEndContext, fontProps]; 

}; - AppendTextToTargetDoc 

< < Copy the initial font, para, and page properties of a doc to nodes in z. >> 
GetlnitiaiDocProps: proc[ 

docFileRef: NSFile. Reference, sourceDoc: DoclnterchangeDefs.Doc, 

session: NSFiie.Session, fp: DoclnterchangePropsDefs-FontProps, 

pp: DoclnterchangePropsDefs-ParaProps, 

pagep: DoclnterchangePropsDefs-PageProps, 

source Left Heading, sourceRightHeading, 

sourceLeftFooting, sourceRightFooting: long pointer to HeadFootText, 
zone: uncounted zone] = { 
procs: DoclnterchangeDefs.EnumProcsRecord ^( 
newParagraphProc: HitNewPar, pfcProc: HitPFC]; 

HitNewPar: DoclnterchangeDefs. NewParagraphProc = { 
pp.basicProps «- paraProps.basicProps; 
pp.sparel <~0; 

IF paraProps.tabStops.LENGTH = 0 then pp.tabStops <- descriptor[nil, 0] 
else { 

Storage: type = record [ 

sequence computed cardinal of DoclnterchangePropsDefs.TabStop]; 
pp.tabStops <- descriptor[ 

zone.NEw[Storage [paraProps.tabStops.LENGTH]], 

paraProps.tabStops. length ] ; 



FORix: CARDINAL IN [0..paraProps.tabStops.LENGTH) DO 
pp.tabStops(ix] <-paraProps.tabStops[ix]; endloop; 

}; 

}; -HitNewPar 

HItPFC: DoclnterchangeDefs-PFCProc = { 
f p 1 «- f ontProps t ; 
pagep f <- pageProps t ; 
IF pageProps-unequalColumnWidths then { 

length: cardinal s pageProps.coiumnWiciths.length; 
pagep.column Widths <~ zone.NEw[ 

OocI nterchangePropsDef s . Col um n WidthsRecord [length]] ; 
FOR i: CARDINAL IN (0..lengthj do 

pagep. col u m n Widths, wi dths[i ] <~ pageProps.col u m n Wi dths. widths(i ] ; 
endloop; 

pagep.columnWidths.length length; 

pagep.columnWidths.spare1 ^ pageProps.columnWidths.spare1 ; 
} 

ELSE pagep.columnWidths nil; 
{ 

procs: DoclnterchangeDefs.EnumProcsRecord <-[ 

newParagraphProc: Local NPProc, textProc; Local TextProc]; 
targetHF: long pointer to HeadFootText nil; 

GrowHF: proc [hf: long pointer to HeadFootText] = { 

IF hf = NIL THEN {hf | 2one.NEw[HeadFootTextRec [5]]; hf. length 0} 

ELSE 

IF hf.length = hf.maxLength then { 

new: HeadFootText = zone.NEw[HeadFootTextRec [hf.length + 5]]; 
new.length <— hf.length; 

for i: CARDINAL IN [0.. hf.length) do new.list[i] hf.list[i]; endloop; 

zone.FREE[hf]; 

hf ♦-new; 

}; 

}; -GrowHF 

Local NPProc: DoclnterchangeDefs. NewParagraphProc = { 

GrowHF[targetHF]; 
targetHF.Iist[targetHF.Iength] <- [ 

fontProps: fontProps | , v: np[paraProps: paraProps f ]]; 
with hfBound: targetHF.Iist(targetHF.Iength] select from 

np = >{ 

if paraProps. tabStops. length = Othen 

hfBound.paraProps.tabStops <- descriptor[nil, 0] 
else{ 

Storage: type = record [ 

sequence computed CARDINAL of 

DoclnterchangePropsDefs.TabStop]; 
hfBound.paraProps.tabStops <- descriptor( 

zone.NEw(Storage [paraProps.tabStops.LENGTH]], 

paraProps. tabStops. length]; 
FORix: CARDINAL IN [O-.paraProps.tabStops.LENGTH) DO 

hfBound. paraProps. tabStops[ix] <- paraProps.tabStops[ix]; 

endloop; 

}; 
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ENDCASE = > error; 

targetHF.Iength <-targetHF.Iength + 1; 
}; - LocalNPProc 

LocaiTextProc: DoclnterchangeDefs-TextProc = { 
GrowHF[targetHFl; 
targetHF.IistttargetHF.IengthJ <- ( 

fontProps: fontProps t , 

v: text[ 

rb: XString.CopyToNewReaderBody(r: text, z: zone], 

textEndContext: textEndContextJ]; 
targetHF.Iength4-targetHF.Iength + 1; 
}; "LocaiTextProc 

- start of HitPFC 
targetHF <-sourceLeftHeading; 
sourceLeftHeading t <-nil; 
. [] *- OoctnterchangeOefs.Enumerate[[heading[teftHeading]], @procs]; 
targetHF <- sourceRightHeading; 
sourceRightHeading f <- nil; 

[] <- DoclnterchangeOefs.Enumerate[[heading[rightHeading]], @procs]; 
targetHF <-sourceLeftFooting; 
sourceLeftFooting I ♦-nil; 

(1 <- DoclnterchangeDefs.Enumerate([footing(leftFootingll, ©procsj; 
targetHF <-sourceRightFooting; 
sourceRightFooting f «-iviil; 

(] <- DoclnterchangeDefs.Enumerate([footing[rightFooting]], ©procsl; 

}; 

RETURN[stop: trueI; 
}; -HitPFC 

[] <--DoclnterchangeDefs.Enumerate[[docth: sourceDoc]], ©procs]; 
}; -GetlnitialDocProps 

< < Change the name of the new document to be the same as the old doc. > > 
SetNewDocName: proc [ 

oldDoc: NSFile.Reference, newDoc: NSFile. Handle, 

newDocSession: NSFile.Sessionl = { 

oldDocFile: NSFile.Handle <- NSFile.OpenByReference[ 

reference: oldDoc, controls: [lock: share, access: [read: true]]]; 
attRec: NSFile.AttributesRecord; 
attArray: array [0..01 of NSFIIe.Attribute; 
NSFIIe.GetAttri butes[ 

file: oldDocFlle, selections: [interpreted: [name: true]], attributes: ©attRec]; 
attArray [0] [name[value: attRec. name]]; 
NSFile. ChangeAttri butes[ 

file: newDoc, attributes: DESCRiPTOR[attArray], session: newDocSession]; 
NSFile.Close[oldDocFile]; 
NSFile.FreeWords( 

DESCRiPTOR[attRec.name.bytes, NSString.WordsForString[attRec.name.length]]]; 
}; -SetNewDocName 

WrapUpFiling: proc [ 

docFileRef: NSFile.Reference, docFile: NSFile.Handle, 
targetDocSession: NSFile.Session] = { 
refDoc, refDt: NSFile.Reference; 
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fileDt: NSFile.Handle; 
SetNewDocName[ 

oldDoc: docFileRef, newOoc: docFile, newOocSession: targetDocSession]; 
refDoc <- NSFile.GetReference(docFile, targetDocSession]; 
ref Dt <- StarDesktop.GetCurrentDesktopFiled; 
fiieOt <- NSFiie.OpenByReference[refDt, , targetDocSession]; 
NSFiie.Move[docFiie, fileDt, , targetDocSession]; - put new doc on Desktop 
NSFii e.Ci ose(f i I eDt, target DocSessi on] ; 
NSFile.Close{docFlie, targetDocSession]; 
StarDesktop.AddReferenceToDesi(top[refDoc]; 
}; "WrapUpFUing 

Init: PROC = { 

name: XString.ReaderBody 

XString,FromSTRING["Copy Most of Doc (Forked)"^ true]; 
Attention,AddMenultem[ 

Menu Data. Createltem(z, ©name, MakeDocMenuCmdProc]]; 
name <- XString.FromSTRING("Copy Most of Doc (Notifier)"L, true]; 
Attention.AddMenultem( 

MenuData.Createltem[z, ©name, MakeDocMenuCmdProc, 1]]; 
}; ~/nit 

-main code . 

Initd; 

}. 
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Item 


Page 


Item 


Page 


AbortCreation: proc 


11 


Open: proc 


12 


AnchoredFrameProc: type 


14 


OpenStatus: type 


12 


AnchoredFrameType: type 


6 


PageBreakProc: type 


14 


AppendAnchoredFrame: proc 


6 


PaginateOption: type 


4 


AppendAnchoredFrameX: proc 


6 


PFCProc: type 


14 


AppendBreak: proc 


7 


Readonly BreakProps: type 


7 


AppendChar: proc 


7 


ReleaseCaption: proc 


10 


AppendColumnBreak: proc 


7 


ReleaseField: proc 


10 


AppendField: proc 


8 


ReieaseFootIng: proc 


10 


AppendltemToFilllnOrder: proc 


16 


ReleaseHeading: proc 


10 


AppendNewParagraph: proc 


8 


ReieaseSparel: proc 


10 


AppendPageBreak: proc 


8 


Releases pa re2: proc 


10 


AppendPFC: proc 


8 


ReieaseSpare3: proc 


10 


AppendText: proc 


9 


ReieaseSpare4: proc 


10 


AppendTile: proc 


9 


ReieaseTiie: proc 


10 


BreakProps: type 


7 


SetCurrentParagraphProps: proc 


11 


BreakPropsRecord: type 


7 


SetModeProps: proc 


11 


BreakType: type 


7 


SpareProc: type 


■ 15 


Caption: type 


3 


SpareTC: type 


3. 


CaptionObject: type 


3 


StartCreation: proc 


4 


CheckAbortProc: type 


10 


StartCreationStatus: type 


5 


ClearFiliinOrder: PROC 


17 


TextContainer: type 


2 


Close: PROC 


15 


TextProc: type 


15 


ColumnBreakProc: type 


14 


Tile: type 


3 


Doc: TYPE 


3 


TileObject: type 


3 


DocObject: type 


3 


TileProc: type 


15 


Enumerate: proc 


13 






EnumerateFiillnOrder: proc 


16 






EnumProcs: type 


13 






EnumProcsRecord: type 


13 






Error: error 


16 






ErrorCode: type 


16 






Field: type 


3 






FieldObject: type 


3 






FieidProc: type 


14 






FilllnOrderltemType: type 


16 






FilllnOrderProc: type 


17 






FinishCreation: proc 


10 






FinishCreationStatus: type 


11 






Footing: type 


3 






FootingObject: type 


3 






GetModeProps: proc 


11 






Heading: type 


3 






HeadingObject: type 


3 






instance: type 


3 






InstanceNii: Instance 


3 






NewParagraphProc: type 


14 
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73.1 Overview 

This interface contains procedures and data types used to describe the properties in 
documents; it is intended for use with all the *lnterchangeOefs interfaces. 

Most records below have spare fields for future use. When specifying values for these, it is 
important to use zero if you do not know of a correct value to use. 

73.2 Interface Items 

73.2.1 Frame Properties 

The chief type in this section is the FramePropsRecord, which describes the properties of an 
anchored frame. 

FrameProps: TYPE ■ long pointer to FramePropsRecord; 

ReadoniyFrameProps: TYPE « long pointer to readonly FramePropsRecord; 

FramePropsRecord: TYPE a RECORD [ 
borderStyie: BorderStyle, 
borderThickness: cardinal, 
frameOims: FrameOimSr 
fixedWidth, 
fixedHeight: bool, 
span: Span. 

verticalAlignment: VerticalAiignment, 

horizontalAiignment: HorizontalAlignment, 

topMarginHeight, 

bottom Margin Height, 

ieftMarginWidth, 

rightMarginWidth: CARDINAL, 

sparel: long cardinal]; 
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BorderStyle: TYPE a machine dependent { 

invisibie(0),soiid, dashed, broken, dotted, double, firstAvaiiabie, lastAvaiiable(255)}; 

borderStyle specifies the characteristics of the lines that make up the frame border. 

borderThickness specifies the thickness of the frame border. This value is in units of 1/72 
inch. Note that borderThickness depends on the borderStyle specified: for double borders 
borderThickness can range from 3 to 18 in multiples of 3 points (a '*point" is 1/72 inch), 
while for all other borderStyles borderThickness can range from 1 to 6 points. 

FrameOims: type ■ record [w, h: cardinal]; 

frameOims specifies the height and width of the frame. These dimensions are also in units 
of 1/72 inch. 

f ixedWidth and f ixedHeight indicate whether the frame will expand when necessary. 

Span: TYPE > machine dependent {partialColumn(O), 

fullColumn, partialPage, fuliPage, firstAvaiiabie, lastAvaiiable(255)}; 

span specifies how much of the page the frame occupies. Currently only fuliColumn and 
fuliPage are supported. 

VerticalAlignment: TYPE ■ machine dependent { 

top(0), bottom, floating, firstAvaiiabie, lastAvallable(255)}; 

HorizontalAlignment: TYPE « machine dependent { 

left(0), centered, right, floating, firstAvaiiabie, iastAvailabie(255)}; 

vertical and horizontal Alignment specify the alignment of the frame relative to the page. 

topMarginHeight, bottomMarginHeight, leftMarginWidth, and rightMarginWldth are the 
margins of the frame, in units of 1/72 inch. 

all items marked as spare are for future use. 

73.2.2 Page Properties 

The chief type in this section is the PagePropsRecord, which describes the various 
properties that can be associated with a page in a ViewPoint document. 

PageProps: TYPE ■ long pointer to PageProps Record; 

ReadonlyPageProps: TYPE ■ long pointer to readonly PagePropsRecord; 

PagePropsRecord: TYPE ■ record [ 
pageDims: PageOims, -layout 
topMarginHeight, 
bottomMarginHeight, 
leftMarginWidth, 
rightMarginWldth: cardinal, 
startingPageSide: PageSide, 
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bindingMarginWidth: cardinal, 
nCoiumns: cardinal, - column structure 
baiancedCoiumns, unequaiCoiumnWidths: bool, 
columnSpadng: cardinal, 
column Widths: ColumnWidths, 
startingPageNumber: cardinal, -page numbering 
pageNumberFormat: NumberFormat, 
restartPageNumbering: bool, 
startingLineNumber, - line numbering 
lineNumberlnterval: cardinal, 
lineNumberFormat: NumberFormat, 
lineNumberLocation: LineNumberLocation, 
headingStartsOnThisPage, ~ heading 
headingSameOnLeftRightPages, 
footingStartsOnThisPage, - footing 
footingSameOnLeftRightPages:BOOL, 
sparel: LONG cardinal]; 

PageOims: type • machine dependent record [w, h: cardinal]; 

PageSide: type » machine dependent { 

nil(O), left, right, firstAvailable, lastAvailable(255)}; 

pageDims are the width and height of the table, in units of 1/72 inch. topMarginHeight, 
bottomMarginHeight, leftMarginWidth, and rIghtMarginWidth describe the page 
margins; these values are also in units of 1/72 inch. startingPageSide indicates whether 
the first page of the document should be a left-hand page or a right-hand page; nil means 
that there is no difference between the two. bindingMarginWidth is the width of the 
binding margin, if there is one. 

nColumns, balancedColumns, unequalCoiumnWidth, and columnSpacing determine 
column structure. nColumns is the number of columns; balancedColumns specifies 
whether the length of the column is equal to the length of the page. unequalCoiumnWidth 
indicates that the columns may have varying widths. columnSpacing is the amount of 
space between columns, in units of 1/72 inch. A maximum of 50 column widths may be 
specified. 

ColumnWidths: TYPE ■ long pointer to ColumnWidthsRecord; 

CoiumnWidthsRecord: TYPE « record [ 
length: cardinal, 
sparel : long cardinal, 

widths: sequence maxLength: cardinal of ColumnWidthRecord]; 
Column Width Record: TYPE ■ record [ 

W: CARDINAL, 

sparel: long cardinal]; 

The CoiumnWidthsRecord record contains the number of columns (length) and a sequence 
that contains the width of each column. Spare fields are included in both the record and 
each of the sequence elements. 
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startingPageNumbers, pageNumberFormat, and restartPageNumbering describe the page 
numbering properties. startingPageNumber indicates the page number at which the 
numbering should start; restartPageNumbering specifies whether renumbering should 
restart for this page, or continue from where the last numbering left off. 

NumberFormat: type ■ machine dependent { 

cardinal(O), lowerCaseLetter, upperCaseLetter, lowerCaseRoman, 
upperCaseRoman, firstAvailable, iastAvailable(255)}; 

pageNumberFormat specifies the format of the page number; currently only cardinal is 
implemented. 

LineNumberLocation: TYPE ■ machine dependent { 

leftMargin(O), rightMargin, outerMargin, bothMargins, 
firstAvailable,IastAvaiiable(255)}; 

startingLineNumber, lineNumberlnterval, lineNumberFormat, and lineNumberLocation 
are not currently implemented: 

The remaining properties describe headings and footings. headingStartsOnlhisPage and 
footingStartsOnThisPage indicate whether the designated heading/footing should start on 
this page or the next; HeadingSameOnLeftRightPage and footingSameOnLeftRlghtPages 
specifies whether all pages have the same heading/footing. sparel is for future use. 

73.2.3 Field Properties 

The chief field property is the FieldPropsRecord, which describes the properties of a field. 

FieidProps: type ■ long pointer to FieldPropsRecord; 

Readonly FieldProps: type « long pointer to readonly FieldPropsRecord; 

FieldPropsRecord: type « record [ 

language: MultiNationai.Language, 

length: CARDINAL, 

required: bool, 

skiplf : SkipifChoiceType, 

stopOnSkip: bool, 

type: FieldChoiceType, 

filllnRuier 

description, 

format, 

name, 

range, 

skiplf Field: xstrmg.ReaderBody, 
filllnRuleRuns: FontRuns, 
sparel: long cardinal]; 

language determines the format of date and amount fields. There are many formats, so you 
would have to check the format for each particular language. 
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length specifies the maximum number of logical characters the field may contain. 

required indicates whether the user is required to fill in the field. If required is true, the 
user will not be able to use next or skip to advance to the next field until this field has a 
value. 

SkiplKhokeType: TYPE ■ machine dependent { 

empty(0), notEmpty« never, always, firstAvailable, iastAvailable(255)}; 

skiplf defines the conditions under which the field can be skipped when the user presses the 
NEXT key. stopOnSkIp specifies whether the skipping action should stop at this field or not. 

FieldChoiceType: TYPE ■ machine dependent { 

any(O), text, amount, date, firstAvailabie, lastAvaiiabie(255)}; 

type specifies the type of data that can be in the field, any indicates that the field can 
contain any characters, including frames (but not other fields), text indicates that the field 
can contain only letters, digits, and symbols entered from the keyboard, amount indicates 

that the field can contain only numbers, spaces, and the following symbols: + *$,.(). 

date specifies that entries in the field can contain only a date. 

fiilinRuie defines the fill-in rule for this field. 

description is posted for each field entered with the next key if the document is set to 
prompt for fields, format controls the format in which information is presented. For a type 
of text, this property defines a required pattern that must be matched. For a type of 
amount or date, this field controls the form in which the contents of the field are presented, 
regardless of how the user enters them. For a type of any, the format property is not used. 

name is the name of the field. If no name is provided, the field will automatically be named 
Fields, as in Fieldl, Field2, and so on. 

range defines a specific range of acceptable entries. 

skiplf Field contains the name of the field that vnll appear in the property sheet Skip if field. 

filllnRuleRuns is an auxiliary data structure that the client can attach to the xstring.Reader 
that describes the fill-in rule for the field. A font run describes the subsequences of 
characters within a Reader that have the same font attributes. 



73.2.4 Font Properties 

The FontPropsRecord is the chief type in this Section. Section 73.2.4.1 describes the 
fontOesc field; section 73.2.4.2 describes the other fields in a FontPropsRecord. 

FontProps: TYPE ■ long pointer to FontPropsRecord; 

ReadonlyFontProps: type ■ long pointerto readonly FontPropsRecord; 

FontPropsRecord: TYPE ■ record [ 
fontOesc: FontDescription, 

offset: INTEGER, 
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foregroundBackground: ForegroundBackground, 

nUnderiines: cardinal, 

strikeout: bool, 

placement: Placement, 

toBeDeieted, 

revised: bool, 

width: Width. 

sparel : long cardinal] ; 

73.2.4.1 FontOescriptiLon 

FontOescription: TYPE ■ record [ 
family: Family, 

designVariant: DesignVariant, 
posture: Posture, 
weight: Weight, 
pointSize: cardinal, 
serif ness: Serif ness, 
sparel : long cardinal]; 

Family: type ■ machine dependent { 

century(O), frutiger(1), titan(2), pica(3), trojan(4), vintage(5), elite(6), 
ietterGothic(7), master(8), cubic(9), roman(1 0), scientif ic(1 1 ), gothic(1 2), 
boid(13), ocrB(14), spokesman(1 5), xeroxLogo(16), century Thin(1 7), 
scientificThin(18), helvetica(19), helveticaCondensed(20), optima(21), 
times(22), baskervrlle(23), spartan(24), bodoni(25), palatino(26), 
caledonia{27), memphis(28), excelsior(29), olympian(30), univers(31), 
universCondensed(32), trend(33), boxPS(34), terminai(35), ocrA(36), iogo1(37), 
logo2(38), logo3(39), geneva2(40), times2(41), square3(42), courier(43), 
futura(44), prestige(45), aLLetterGothic(46), centurySchoolBook(47), 
firstUnused(48), lastUnused(510), backstop(51 1)}; 

family is the font family. 

DesignVariant: type > machine dependent { 

null(O), roman, italic, firstAvailable, lastAvailable(255}}; 

designVariant specifies whether the character is roman or italic, null is not currently a 
valid value. 

Posture: type ■ machine dependent { 

null(O), upright, slanted, backslanted, firstAvailable, lastAvailable(255)}; 

posture indicates the slant (stress) of the character, if any. null is not currently a valid 
value. 

Weight: type > machine dependent { 

null(O), ultralight, extraUght, light, semiLight, medium, semiBold, bold, 
extfaBold, ultraBold, firstAvailable, lastAvailable(255)}; 

weight is the thickness of the character. 
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pointSize is the size of the font. Note that this value must be in the subrange [0..1023]. 

Serifness: TYPE « machine dependent { 

nuil(O), serif, sansSerif , firstAvailabie, lastAvaiiabie(255)}; 

serifness indicates whether or not the character has serifs, null is not currently a valid 
value. 

sparel is for future use. 

73.2.4.2 The other fields in FontPropsRecord 

offset is the offset of the character from the baseline. 

ForegroundBackground: TYPE « machine dependent { 

null(OK biaci(OnWhite, whiteOnBtack, firstAvaiiable, iastAvaiiabie(255)}; 

foregroundBackground indicates the color of the character relative to the display. 

nUnderiines indicates the number of times that the character is underlined; the value must 
be in the range [0..2]. 

strikeout indicates whether or not the character has been struck through. 

Placement: type « machine dependent{ 

null(O), sub, subSub, subSuper, super, superSub, superSuper, userSpecif ied, 
fIrstAvaiiable, tastAvailable(255}}; 

placement indicates the position of the character relative to the line. 

toBeOeleted indicates "normal** text that has been marked for deletion in Redlining mode. 

revised indicates text that was typed in while Redlining was on but before finalizing the 
Redlined revisions. 

Width: type ■ machine dependent { 

proportional(O). quarter, third, half, threeQuarters, full, firstAvailable, 
iastAvailable(255)}; 

width is used for Japanese text and should be set to proportional to get normal characters. 
73.2.5 Font Runs 

FontRuns are used to associate font properties with text. XString provides no facilities for 
associating font properties with text; DodnterchangePropsOefs allows the client to create 
font information structures that point into XString structures to make the association. 

The data structures in this section mark font runs, which are consecutive characters with 
the same font. A FontRunsRec describes the font, while a cardinal value describes where 
the font starts in the text. 
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In addition, this interface allows the client to enumerate the font runs in a given XString ^ttii^ 
body of text. 

Run: TYPE ■ RECORD [ 

props: FontPropsRecord, 
index: cardinal, 
context: xstring.Context, 
sparel: LONG cardinal]; 

A Run indicates the beginning of a font run. props is the field describing the font used in 
the font run. index is the byte offset in the byte sequence that holds the text; it is the byte 
offset from the beginning of the byte sequence to the byte after the byte run. context is the 
XString context describing the next byte run. The context of the first byte run is contained 
in the reader body. See the next section for further explanation. 

FontRuns: TYPE « long pointer to FontRunsRec; 

FontRunsRec: type • record [ 
length: cardinal, 
sparel : long cardinal, 

runs: sequence maxLength: cardinal of Run]; 

FontRuns points to FontRunsRec, which is a record containing a sequence of Runs. 

EnumerateFontRuns: proc[ jtum^ 
r: xstring.Reader, 
runs: FontRuns, 
proc: FontRunProc, 
clientOata: long pointer <~ nil] 
returns [stopped: bool]; 

FontRunProc: type ■ proc [ 
r: xstring.Reader, 
fontProps: FontProps, 
clientData: long pointer] 

RETURNS [stop: BOOL 4- FALSE]; 

EnumerateFontRuns allows you to perform some action for each font run in an 
xstring.Reader. FontRunProc is a call-back procedure that you pass to EnumerateFontRuns. 
If FontRunProc returns stopped » true, the enumeration stops and EnumerateFontRuns 
returns stopped ■ true. ciientOata is client defined data that you pass to 
EnumerateFontRuns, which passes it to FontRunProc every time FontRunProc is invoked. 



73.2.5.1 Meaning of Index and Context Fields in Run 

As stated earlier, index is the index into the XString of the byte following that run. context 
is the xstring.Context in effect after that run. Here are two examples: 

A ReaderBody with offset = 0, limit = 12, with bytes abcdefghijkl; font runs that describe 
the first three bytes as fontA, the next four as fontB, and the last five as fontC would be: 
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fontRun 0: [props: fontA, index: 3, context: ...] 
fontRun 1: [props: fontB, index: 7, context: ...] 
fontRun 2: [props: fontC, index: 12, context: ...J 

A ReaderBody with offset = 7, limit = 19, with bytes abcdefghijkl; font runs that describe 
the first three bytes as fontAj the next four as fontB^ and the last five as fontC would be: 

fontRun 0: [props: fontA, index: 10, context: ...1 
fontRun 1 : [props: fontB, index: 14, context: ...] 
fontRun 2: [props: fontC, index: 19, context: ...] 

73.2.6 Paragrairh Properties 

The chief type in this section is the ParaPropsRecord, which describes the possible 
paragraph properties. 

ParaProps: TYPE a long pointer to ParaPropsRecord ; 

ReadonlyParaProps: TYPE ■ long pointer to readonly ParaPropsRecord; 

ParaPropsRecord: TYPE ■ record [ 
basicProps: BasicPropsRecord, 
tabStops: TabStops, 
sparel: LONG cardinal]; 

basicProps describes all standard paragraph properties (those on the Paragraph property 
sheet); tabStops describes the current tab settings (the information on the Tab Settings 
property sheet). 

The following sections describe the BasicPropsRecord and TabStops records in detail. 

73.2.6.1 BasicPropsRecord 

BasicProps: TYPE • long pointer to BasicPropsRecord; 

ReadonlyBasicProps: type ■ long pointer to readonly BasicPropsRecord; 

BasicPropsRecord: TYPE a record [ 
preLeading, 
postLeading, 
leftindent, 
rightlndent, 
lineHeight: cardinal, 
paraAlignment: ParaAlignment, 
justified, 
liyphenated, 

keepWithNextPara: bool, 
language: MuitiNational.Language, 
streakSuccession: StreakSuccession, 
defaultlabStopSpacing: OefaultTabStopSpacing, 
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defaultTabStopAiignment: TabStopAlignment, 
sparel : long cardinal]; 

preLeading and postLeading are the spacing before and after the paragraph respectively; 
these values are in units of 1/72 inch. 

leftlndent and rightlndent are the left and right paragraph margins; these values are in 
units of 1/72 inch; 

lineHeight is the default line height for the paragraph; this value is in units of 1/72 inch. 

ParaAlignment: TYPE ■ machine dependent { 

ieft(0), center, right, firstAvailable, iastAvaiiable(255)}; 

paraAiignment indicates the alignment of the paragraph relative to the containing text 
column or text block. 

justified when true, causes the text in the paragraph to stretch to make a straight right 
edge. 

hyphenated indicates whether the paragraph will be hypenated at the end of lines to 
improve justification. 

keepWithNextPara indicates whether the pagination operation should attempt to keep this 
paragraph on the same page or column as the next one. 

language is the language for the paragraph; this information is used for formatting 
decimal tabs. It is also used when items are added to the paragraph (e.g., a field inherits 
the p€Lragraph language when added to the paragraph). 

StreaicSuccession: TYPE ■ machine dependent { 

leftToRight(O), rightToLeft, firstAvaiiable, lastAvailable(255)}; 

streakSuccession specifies whether a "streak" of characters should logically be read from 
left to right (e.g. English) or right to left (e.g. Hebrew). 

TabStopOffset: type ■ cardinal; 

DefaultTabStopSpacing: type ■ cardinal; 

defaultTabStopSpacing is the default number of spaces between tabs. 

TabStopAlignment: type « machine dependent { 

left(O), center, right, decimal, firstAvailable, iastAvaiiable(255)}; 

defaultTabStopAiignment is the default alignment for tabs: tabs can be relative to the left 
paragraph margin, the center of the paragraph, the right paragraph margin, or decimal 
points. 

sparel is for future use. 
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73.2.6.2 Tabs 

TabStops: TYPE ■ long descriptor for array of TabStop; 

TabStop: type ■ record [ 
dotLeader: boolean, 
tabStopOffset: TabStopOffset, 
tabStopAlignment: TabStopAiignment, 
sparel: long cardinal]; 

tabStops describes the currently set tabs for the paragraph. 

dotLeader indicates whether the tab has leader dots. tabStopOffset indicates the location 
of the tab, relative to the paragraph margin. tabStopAlignment indicates the alignment of 
the tab. 

Any array of tabstops used to create or modify a document object must be sorted in 
increasing order of tabStopOffsets. A tabStopOffset that is equal to a previous one is 
ignored. During enumeration, tabstop arrays passed to the client will always be sorted in 
this manner. The maximum number of tabstops that may be set in any paragraph is 
nTabsMax. 

nTabsMax: cardinal a 100; 

nTabsMax is the maximum number of tabs that there can be in a paragraph. 

73.2.7 Mode Properties 

Mode properties describe the commands in the document and auxiliary menus of a 
Viewpoint document. 

ModeProps: type * long pointer to ModePropsRecord; 

ReadonlyModeProps: TYPE » long pointer to readonly ModePropsRecord; 

ModePropsRecord: TYPE * record [ 
structureShowing, 
nonPri nti ngShowi ng, 
coverSheetShowing, 
promptFields: bool, 
sparel: LONG cardinal]; 

structureShowing, nonPrintingShowing, coverSheetShowing, and promptFields specify 
the appearance of the displayed document. 

BooleanFalseDefauit: TYPE ■ bool<- false; 

ModeSelections: type ■ packed array ModeElements of BooleanFalseDefauit; 



73-11 



DocInterchangePropsDefs 



ModeElements: type a { 

structureShowrng, nonPrintingShowing, coverSheetShowing, promptFieids, 
sparel, spare2, spareS, spare4, spares, spare6, spare?, spareS}; 

ModeSelections are used to specify which ModeElements of a document should be acted 
upon. 

73.2.8 Constants 

The nuli*Props constants are declared so that clients may initialize property records with 
"neutral** properties. In most cases, each field value is the same as what would be set by the 
corresponding Get^PropsOefauits operation (sec 73.2.8). 

nullFrameProps: FramePropsRecord ■ [ 
borderStyle: solid, 
borderThickness: 2, 
frame Dims: [72, 721, 
fixedWidth: false, 
fixedHeight: false, 
span: partiaiColumn, 
verticalAiignment: floating, 
horizontalAiignment: centered, 
topMarginHeight: 0, 
bottomMarginHeight: 0, 
leftMarginWidth: 0, 
rightMarginWidth: 0, 
spare1:0]; 

nuilPageProps: PagePropsRecord » [ 
pageOims: [0, 0], 
topMarginHeight: 0, 
bottomMarginHeight: 0, 
leftMarginWidth: 0, 
rightMarginWidth: 0, 
startingPageSide: left, 
bindingMarginWidth: 0, 
nColumns: 1, 
balancedColumns: false, 
unequalCoiumnWidths: false, 
columnSpacing: 0, 
coiumnWidths: nil, 
startingPageNumber: 1, 
pageNumberFormat: cardinal, 
restartPageNumbering: false, 
startingLineNumber: 1, 
lineNumberinterval: 1, 
lineNumberFormat: cardinal, 
lineNumberLocation: leftMargin, 
headingStartsOnThisPage: true, 
headingSameOnLeftRightPages: true, 
footingStartsOnThisPage: true. 
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footingSameOnLeftRightPages: true, 
sparel: 0]; 

nuilCoiumnWidth: ColumnWidthRecord ■ [ 
w: 0, 

sparel: 0]; 

nuilFieidProps: FieldPropsRecord ■ [ 
language: USEngiish, 
length: 0, 
required: false, 
skiplf: never, 
stopOnSkip: false, 
type: any, 

filllnRule: xstring.nullReaderBody, 
description: xstring.nullReaderBody, 
format: xstring.nullReaderBody, 
name: xstring.nullReaderBody, 
range: xstring.nuilReaderBody, 
skiplfField: xstring.nullReaderBody, 
filllnRuieRuns: nil, 
sparel: 0]; 

nuilFontProps: FontPropsRecord a [ 
fontOesc: nullFontOescription, 
offset: 0, 

f oregroundBackground : blackOnWhite, 

nllnderlines: 0, 

strikeout: false, 

placement: null, 

toBeDeleted: false, 

revised: false, 

width: proportional, 

sparel :0]; 

nullFontOescription: FontDescription « [ 
family: modern, 
design Variant: roman, 
posture: upright, 
weight: medium, 
pointSize: 12, 
serifness: sansSerif, 
sparel: 0]; 

nullRun: Run ■ [ 

props: nullFontProps, 
index: 0, 

context: xstring.unknownContext, 
sparel: 0]; 

classic: Family « century; 
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modern: Family ■ frutiger; 

nullParaProps: ParaPropsRecord > [ 
basicProps: nuilBasicProps, 
tabStops: oescriptor[nil, 0], 
sparel : 0]; 

nullBasicProps: BastcPropsRecord ■ [ 
preLeading: 0, 
postLeading: 0, 
leftindent: 0, 
rightlndent: 0, 
lineHeight: 12, 
paraAlignment: left, 
justified: false, 
hyphenated: false, 
keepWithNextPara: false, 
language: USEngiish, 
streakSuccession: leftToRight, 
defaultTabStopSpacing: 18, 
defaultTabStopAllgnment: left, 
sparel : 0]; 

nullTabStop: TabStop * [ 
dotLeader: false, 
tabStopOffset: 0, 
tabStopAlignment: left, 
sparel : 0]; 

nullModeProps: ModePropsRecord a [ 
structureShowing: false, 
nonPrintingShowing: FALSE, 
coverSheetShowing: false, 
promptFieids: false, 
sparel : 0]; 

73.2.9 Default Properties 

The Get*PropsDefaults procedures are called to obtain default values for property fields. 
These procedures differ from the constants in that they may obtain information from the 
user profile. Before calling any of these procedures, the client must declare a record of the 
appropriate type and pass its address to the Get*PropsOefaults procedure. None of these 
procedures allocate any additional data that the client would later have to free. 

GetFramePropsOefauits: proc [props: FrameProps]; 

GetPagePropsOefauits: proc [props: PageProps]; 

GetFieidPropsOefaults: proc [props: FieidProps]; 



GetFontPropsDefaults: proc [props: FontProps]; 
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GetParaPropsOefauits: proc [props: ParaProps]; 
GetModePropsOefauits: proc (props: ModeProps]; 
GetPageNumberOelimiter: proc returns [xchar.Character]; 
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74.1 Overview 

EquationlnterchangeDefs provides utilities for creating and enumerating the content of 
anchored equation frames. It is meant to be used in coi^'unction with OodnterchangeOefs. 

An equation is a container for sub-parts, each of which is either a single object (like a 
character or parenthesis) or an object that, like an equation, contains sub-parts itself. 
Examples of the latter include fractions, integrals, and matrices. The data structure that 
represents this "thing that contains other thin^'- is the Handle, defined below. A handle is 
created by calling StartEquation and is passed to most of the routines in this interface. A 
typical scenario for creating a doctunent with an equation frame in it would be: 

doc <- DoclnterchangeOefs.StartCreation[...]; 
h <-StartEquation[doc]; 

Append... [h, ...]; ~ add an object to h. Ret any Append* routine below. 

[equation, ...] FinishEquation(hl; 

[...] 4- DoclnterchangeDefs.AppendAnchoredFrame( 

to: doc, type: equation, content: equation]; 
[...] 4- OoclnterchangeOefs.FintshCreation[@doc]; 

All the Append"* routines defined below add an object to the end of a container's list of 
objects. 

Most records below have spare fields for future use. When specifying values for these, it is 
important to use zero if you do not know of a correct value to use. 

74.2 Interface Items 

74.2.1 General data types 

Handle: TYPE ■ long pointer to Object; 

Object: type ■ record [ 
zone: uncounted zone, 

equation: OQClnterchangeOefs.lnstance, 
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sparel : long cardinal, 
private: array [0..0) of word]; 

The zone is a normal type of scratch zone that will be destroyed when 
Dodnter€hang«o«fs.FinishCreatton or Oocinterchang«Ottfs.AbortCreation has been called on the 
document. Clients are free to use this zone for node allocation. 

equation uniquely identifies an equation or an equation sub-part within a document. 

Looks: TYPE ■ MACHINE DEPENDENT {normai(O), bold, italic, iastAvailable(255)}; 

Size: type • machine dependent { 

smailest(Oh smail(l), regular(2), Iarge<3), lastAvailable<255)}; 

EquationCharProps: type ■ long pointer to EquationCharPropsRecord; 

ReadonlyEquationCharProps: type ■ long pointer TO readonly 
EquationCharPropsRecord; 

EquationCharPropsRecord: TYPE ■ record [ 
loolcs: Looks, 
size: Size, 

spares: array [0..8) of word]; 

74.2.2 Equation creation 

StartEquation: proc [doc: DocfnterchangeDefs.Doc] returns [Handle]; 

Creates a handle that, when passed to FinishEquation, will yield the content of an anchored 
equation frame. The content of the frame is to be passed to 
Docinterchang«D«fs.AppendAnchoredFrame. See FinishEquation. May raise 
Dodnt«rchangeD«fs.Error[documentFull, readonlyOoc, outOf DiskSpace, outOfVM]. 

EquationProc: type a proc [h: Handle, clientData: long pointer]; 

Procedures of this type are passed to certain Append* routines (the routines that create 
objects that contain other equation objects). The Equationlnterchange implementation 
then calls this procedure back in order to fill in a particular sub-part. The client proc 
should do this by calling various Append* routines with the passed handle. See the 
Append* routines. 

Side: type ■ {left, right}; 

Specifies a side for objects like parentheses, brackets, and braces. 

AppendBrace: PROC(h: Handle, side: Side, props: ReadonlyEquationCharProps]; 

Appends a curly brace to the handle, props.looks should always be normal. May raise 
Docinterchangeo«fs.Error[documentFull, readoniyOoc, outOfOiskSpace, outOfVM, 
badParameter] (badParameter if props.looks # normal). 

AppendBracket: proc [h: Handle, side: Side, props: ReadonlyEquationCharProps]; 
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Appends a square bracket to the handle, props.looks should always be normal. May raise 
oocinterchangeOefs.Error[documentFuii, readonlyOoc, outOfDiskSpace, outOfVM. 
badParameter] (badParameter if props.looks # normal). 

AppendCharacter: proc [ 

h: Handle, character: xchar.Character, props: ReadonlyEquationCharPrpps]; 

Appends a character to the handle. May raise Doclnt«rchang«D«fs.Error[documentFull, 
readonlyOoc, outOf DiskSpace, outOfVM]. 

AppendStrIng: proc [ 

h: Handle, string: xstring.Reader, props: Readonly EquationCharProps]; 

Appends a string to the handle. Each character of the string is given the designated props. 
May raise Docinterchang«D«fs.Error[documentFull, readonlyOoc, outOfDiskSpace, 
outOfVM]. 

AppendFraction: PROC[ 

h: Handle, size: Size, numerator, denominator: EquationProc, 
clientOata: LONG pointer]; 

Appends a fraction to the handle. During the call to AppendFraction, numerator and 
denominator are called back. Each should fill in their respective parts of the fraction via 
more Append*' routines (passing the handle that was passed to them). May raise 
oocinterchang«oefs.Error[documentFull, readonlyOoc, outOf DiskSpace, outOfVM]. 

IntegralType: TYPE « machine oepenoent{ 

integral(O), linelntegral(l), verticalBar(2), lastAvailable(255)}; 

Appendlntegral: proc[ 

h: Handle, props: ReadonlyEquationCharProps, type: IntegralType, 
lowerBound, upperBound: EquationProc, clientOata: long pointer]; 

Appends an integral to the handle, props.looks should always be normal. During the call 
to Appendlntegral, lowerBound and upperBound are called back. Each should fill in their 
respective parts of the integral via more Append* routines (passing the handle that was 
passed to them). May raise Do€int«rchangeD«fs.Error[documentFull, readonlyOoc, 
outOf DiskSpace, outOfVM, badParameter] (badParameter if props.looks # normal). 

AppendLimit: proc[ 

h: Handle, props: ReadonlyEquationCharProps, range: EquationProc, 
clientOata: long pointer]; 

Appends a limit to the handle, props.looks should always be normal. During the call to 
AppendLimit, range is called back. It should fill in the range of the integral via more 
Append* routines (passing the handle that was passed to range). May raise 
Do€inter€hangeOef$.Error[documentFull, readonlyOoc, outOfOiskSpace, outOfVM, 
badParameter] (badParameter if props.looks # normal). 

Clearance: type ■ [-63..64]; - units are 1/72 inch. 
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ColumnAlignment: TYPE a machine dependent { 

ieft(0), rightd), centered(2K decimal(3), iastAvaiiable(255)}; 

RowAlignment: type ■ machine dependent { 

top(0), bottom<1), centered(2), onbaseline(3), lastAvaiiabie(255)}; 

NextOrder: type ■ machine dependent {byrow(0Kbycoi(1)JastAvailabie(255)}; 

EquationMatrixProps: type • long pointer to EquationMatrixPropsRecord; 

ReadonlyEquationMatrixProps:TYPE ■ long pointer to readonly 
EquationMatrixPropsRecord; 

EquationMatrixPropsRecord: type ■ record [ 
size: Size, 

ctCols, ctRows: cardinal [1..2561, 
dearanteinterCoi, ciearancelnterRowr Clearance, 
rowalignment: RowAlignment, 
coialignment: CoiumnAlignment, 
nextorder: NextOrder. 
sparel: LONG cardinal]; 

MatrixCellProc: type ■ proc [ 

h: Handle, row, column: cardinal [1..256], clientOata: long pointer]; 

AppendMatrix: proc [ 

h: Handle, props: ReadoniyEquationMatrixProps, proc: MatrixCellProc, 
clientData: long pointer]; 

Appends a matrix to the handle. During the call to AppendMatrix, proc is called back once 
for each cell. The proc should fill in the appropriate cell of the matrix via more Append* 
routines (passing the handle that Was passed to proc). The client's proc should not assume 
it is being called in any particular order relative to other cells in the same matrix. May 
raise Docint«rchang«D«fs.Error(documentFulf, readonlyOoc, outOfDiskSpace, outOfVM]. 

AppendOther: proc [h: Handle, data: long unspeofied, clientData: long pointer]; 

AppendOther is for future use. It is currently unimplemented. 

AppendOverBar: proc [ 

h: Handle, size: Size, equation: EquationProc, clientData: long pointer]; 

Appends an overbar to the handle (this is Just a horizontal bar over an equation sub-part). 
During the call to AppendOverBar, equation is called back. It should fill in the pieces 
underneath the overbar via more Append* routines (passing the handle that was passed to 
equation). May raise DocinterchangeD«fs.Error[documentFull, readonlyDoc, 
OutOfDiskSpace, outOfVM]. 

AppendParenthesis: proc [h: Handle, side: Side, props: ReadoniyEquationCharProps]; 
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Appends a parenthesis to the handle, props.iooks should always be normal. May raise 
OocinterchangeOefs.Error[documentFuli, readonlyOoc, outOfDiskSpace, outOfVM, 
badParameter] (badParameter if props.iooks # normal). 

AppendScript: proc [ 

h: Handle, size: Size, base, superscript, subscript: EquationProc, 
clientOata: LONG POINTER]; 

Appends a base/superscript/subscript thingy to the handle. During the call to 
AppendScript, base, superscript and subscript are called back. Each should fill in their 
respective parts of the whatsit via more Append* routines (passing the handle that was 
passed to them). May raise Oodntttrchang«D«fs.Error[documentFuii, readonlyOoc, 
outOf DiskSpace, outOfVM]. 

SummationType: TYPE ■ machine dependent { 

sum(O), product(1), union(2), intersection(3), lastAvaiiable(255)}; 

AppendSummation: proc[ 

h: Handle, props: ReadonlyEquationCharProps, type: SummationType, 
lowerBound, upperBound: EquationProc, ciientData: long pointer]; 

Appends a summation structure to the handle, props.iooks should always be normal. 
During the call to AppendSummation, lowerBound and upperBound are called back. 
Each should fill in their respective parts of the summation sign via more Append* routines 
(passing the handle that was passed to them). May raise 
OocinterchangeDefs.ErrorCdocumentEull, readoniyDoc, outOf DiskSpace, outOfVM, 
badParameter] (badParameter if props.iooks # normal). 

FinishEquation: proc [h: Handle] 

RETURNS [ 

equation: Oo€lnterchangeD«fs.lnstance, 

equationHeight, equationWidth: long cardinal]; 

Finishes an equation and returns an instance for its content. This should be passed to the 
content parameter of Docint«rchangeO«fs.AppendAnchoredFrame. equationHeight and 
equationWidth are for informative purposes only (they are in 1/72 inch units). 

74.2.3 Equation enumeration 

BraceProc: type « proc [ 

side: Side, props: ReadonlyEquationCharProps, ciientData: long pointer] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

BracketProc: type ■ proc [ 

side: Side, props: ReadonlyEquationCharProps, ciientData: long pointer] 
returns [stop: boolean false]; 

CharacterProc: type ■ proc [ 

character: xchar.Character, props: ReadonlyEquationCharProps, 
ciientData: long pointer] 

RETURNS [stop: BOOLEAN 4- FALSE]; 
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FractionProc: typs ■ proc [ 

size: Size, numerator, denominator: DocinterchangeOefs.lnstance, 
clientData: long pointer] 

RETURNS [stop: BOOLEAN <- FALSE]; 

IntegraiProc: type » proc [ 

props: ReadoniyEquationCharProps, type: IntegralType. 

lowerBound, upperBound: oodnt«rdiang«o«fs.lnstance, clientData: long pointer] 

RETURNS [stop: BOOLEAN 4- false]; 

LimitProc: type ■ proc [ 

props: ReadonlyEquationCharProps, element: Docint«rdiangeO«fs.lnstance, 
clientData: long pointer] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

MatrixElementProc: type « proc [ 

element: oociirt«rdiang«D«fs.lnstance, row, column: cardinal [1..256], 
clientData: long pointer] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

EnumerateMatrixProc: type ■ proc [proc: MatrixElementProc, clientData: long pointer] 
RETURNS [stopped: BOOLEAN 4- false]; 

MatrixProc: type ■ proc [ 

props: ReadoniyEquationMatrixProps, matrixProc: EnumerateMatrixProc, 
clientData : long pointer] 

RETURNS [stop : BOOLEAN 4- FALSE] ; 

OtherObjectType: type ■ machine dependent {firstAvailable(0)JastAvallable(255)}; 

OtherProc: type ■ proc [ 

clientData : long pointer, instance: Docint«rchang«D«fs.lnstance, 
objectType: OtherObjectType] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

The OtherProc is currently unimplemented~it will not be called during an enumeration. 

OverBarProc: type ■ proc [ 

size: Size, element: oo€interchangeDefs.lnstance, clientData: long pointer] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

ParenthesisProc: type ■ proc [ 

side: Side, props: ReadonlyEquationCharProps, clientData: long pointer] 

RETURNS [stop: BOOLEAN FALSE]; 

ScriptProc: type ■ proc [ 

size: Size, base, superscript, subscript: DocinterchangeDefs.lnstance, 
clientData: long pointer] 

RETURNS [stop: BOOLEAN <- FALSE]; 

SummationProc: type « proc [ 

props: ReadonlyEquationCharProps, type: SummationType, 
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lowerBound, upperBound: DocinterchangeOefs.lnstance, clientOata: long pointer] 

RETURNS [stop: BOOLEAN FALSE]; 

EnumProcs: TYPE ■ long pointer to EnumProcsRecord; 

EnumProcsRecord: type ■ record [ 
brace: BraceProc *- mil, 
bracket: BracketProc <- nil, 
character: CharacterProc <- nil, 
fraction: FractionProc nil, 
integral: IntegralProc nil, 
limit: LimitProc 4-nil, 
matrix: MatrixProc <- nil, 
other: OtherProc 4-nil, 
overBar: OverBarProc 4- nil, 
parenthesis: ParenthesisProc nil, 
script: ScriptProc <- nil, 
summation: SummationProc nil]; 

EnumerateEquation: proc [ 

equation: Docint«rchang«o«fs.lnstance, procs: EnumProcs, clientData: long pointer] 
RETURNS [stopped: BOOLEAN 4- false]; 

Enumerat.es an equation. Note that the Instance could be that of an anchored equation 
frame or that of some sub-part. If it's the former, then it should be the content parameter 
passed to a Docintttrchangeo«fs.AnchoredFrameProc. Do NOT pass anchoredFrame (another 
Instance parameter of a Docinter<hangeDefs.AnchoredFfameProc) to EnumerateEquation. 
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74.3 Index of Interface Items 



Item Page 
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AppendScript: proc 5 

AppendString: proc 3 

AppendSummation: PROC 5 
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Clearance: type 3 
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EnumerateEquation: proc 7 
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EquationMatrixPropsRecord: type 4 

EquationProc: type 2 

FinishEquation: proc 5 

FractionProc: type 6 

Handle: type 1 

IntegralProc: type 6 

IntegraiType: type 3 

LimitProc: type 6 

Looks: TYPE 2 

MatrixCeilProc: type 4 

MatrixElementProc: type 6 

MatrlxProc: type 6 

NextOrder: type 4 

Object: type 1 

OtherObjectType: type 6 

OtherProc: type 6 

OverBarProc: type 6 
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Item Page 

Side: type 2 
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StartEquation: proc 2 

SummatlonProc: type 6 

SummationType: type 5 
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75.1 Overview 

GraphicsInterchangeDefs provides utilities for creating and enumerating the contents of 
anchored and nested graphics frames. It is intended to be used in conjunction with 
DodnterchangeOefs. 

75.1.1 Creating Graphics 

To create new graphics, the client starts by calling StartGraphics, which initializes a 
graphics frame so that information can be added to it. This procedure returns a Handle, 
which is a pointer to an opaque type that contains, among other things, a graphics 
container. A graphics container is just an object that can contain graphic objects: a 
graphics container can be an anchored graphics frame, a nested graphics frame, a cusp 
button within a graphics frame, or another similar construct, such as a chart. 

Once the client has a Handle, it can pass that Handle to various Add* routines to add new 
graphics objects, such as curves, rectangles, bitmaps, and text frames, to the graphics 
frame. 

The client can also add nested frames, such as non-anchored graphics frames, cusp buttons, 
or graphics clusters, to the anchored frame. To create these structures, the client should 
call StartGraphicsFrame, StartCuspButton, or StartCluster, respectively. Each of these 
procedures takes a graphics container as a parameter, and returns another graphics 
handle. The client can then use this as the graphics container in other calls to Add* 
routines. 

When everything has been added to a graphics container, the final step is to call a Finish* 
routine: FinishGraphics, FinishButton, FinishGraphicsFrame, or FinishCluster. 
FinlshGraphics returns a graphics handle that can be passed to OoclnterchangeDefs. 

Thus, the scenario for creating a document with a floating graphics frame nested within an 
anchored graphics frame looks something like this: 

1. Call oo<interchangeOefs.StartCreation to get a document handle (doc) . 
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2. Call StartGraphics[doc] to get an anchored frame handle (h). 

3. Call Add'^lh] to add graphics to the anchored frame. 

4. Call StartGraphicsFrame to get a handle for a nested graphics frame (gf h). 

5. Call Add'^Cgf h] to add graphics to the nested frame. 

6. Call FinishGrapicsFrame(gf h] to finish the nested frame. 

7. Call FinishGraphics[h] to complete the anchored frame and get an object of type 
oocint«rchang«o«fs.lnstance (graphics). 

8. Call Docint«rchang«o«fs.AppendAnchoredFrame(graphics]. 

9. Call OoclnterchangeO«fs.FinishCreation[@doc]. 

75.1.2 Reading Graphics 

GraphicsInterchangeDefs also Includes the facilities to read the contents of graphics 
frames. To read a graphics frame, the client should call Enumerate. Enumerate takes as 
parameters a graphics container and a record of call back procedures, one for each of the 
following graphics objects: {bitmap frame, cusp button, cluster, curve, ellipse, form field, 
frame, image, line, point, rectangle, text, triangle, other}. 

Enumerate reads the contents of the graphics container, calling the appropriate procedure 
for each object that it encounters. If the client does not provide a procedure for a particular 
type of object, objects of that type will be ignored. Each of the client-supplied enumeration 
procedures can stop the enumeration if it so desires. 

There are similar procedures to enumerate the contents of cusp buttons. 
EnumerateButtonProgram takes a button program and a record to handle the various 
objects that can be in a button program: new paragraphs and text. 

75.2 Interface Items 

75.2.1 Creating graphics 

After calling a Start* routine to initialize a graphics container, the client will typically call 
various Add* routines to add information to the graphics container. The Add* routines 
defined below add an object to the end of the list of objects in the specified graphics 
container. 

Many property records defined below have spare fields for future use. When specifying 
values for these, it is important to use zero if you do not know of a correct value to use. 

The operations for creating graphics are divided into eight sections, which are: 

1. Start routines, which describes the operations for creating graphic containers 

2. Setting extra frame properties, for dealing with additional properties that only 
anchored frames have 
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3. Adding geometries, for adding simple graphics objects such as curves, ellipses, 
lines, points, rectangles, and triangles 

4. Adding frames, for adding all types of nested frames 

5. Adding to a cusp button, for specifying a cusp button's program 

6. Adding miscellaneous objects, for adding objects not defined in this interface 

7. Release routines, which describes operations similar to the Release* operations in 
DocInterchangeDefs 

8. Finish routines, for wrapping up graphic containers 



75.2.1.1 Start routines 



To create new graphics objects, the client must Rrst call StartGraphics to get an anchored 
frame handle. 

StartGraphics : proc [ 

doc: Oo€lnterchang«0efs.0oc] 
RETURNS [h: Handle]; 

StartGraphics creates a new graphics frame within doc. 

Handle: TYPE ■ long pointer to Object; 
Object: type; 

There are also similar routines to create nested frames within a graphics container. 
StartCluster, StartGraphicsFrame, and StartButton each initialize a nested frame within a 
graphics container. All Start routines retiurn a Handle, which the client can then pass to 
the various Add* routines to add graphics to that graphics container. 

StartCluster: pR0C[h: Handle, box: Box] returns [ch: Handle]; 

StartCluster initializes a set of graphics objects in h. box describes the size and location of 
the cluster relative to the anchored frame; place and dims are in micas. 

Box: TYPE ■ RECORD [place: Place, dims: Dims]; ~ micas 

Place: type ■ record [x, y: long integer]; 

Dims: type ■ record [w, h: long integer]; 

Note that an object's place is always relative to the object that contains it. A place- of [0,0] 
indicates the container's upper left comer. When the container is a graphics frame, the 
upper left corner is the one that includes the margins (even when the frame is anchored). 
Increasing X values indicate more rightward locations, and increasing Y values indicate 
more downward locations. Although an object's dims are declared as long integers, it is 
illegal to specify negative width or height for an object's box. An object's place should 
therefore always indicate its upper left corner. 

Every graphic object, including points and containers, has a box. An object's box.dlms 
define the size of the object. If a client specifies a box that is too small for an object in a call 
to an Add* routine, then only that part of the object which lies inside the box will be 
displayed. 
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When graphic objects are encountered during enumeration, the data passed to the client 
procedure always follows the above rules. 

StartGraphicsFrame: proc [ 
h: Handle, 
box: Box, 

frameProps: ReadoniyFrameProps, 
name, description: xstring.Reader ^nil, 
spareProps: long pointer nil, 
wantTopCaptionHandie, 
wantBottomCaptionHandle, 
wantLeftCaptionHandle, 
wantRightCaptionHandle: boolean 4- false] 

RETURNS [ 

gfh: Handle, 

topCaption, bottomCaption, 

leftCaption, rIghtCaption: Docinterchang«o«fs.Caption]; 

StartGraphicsFrame initializes a nested graphics frame in h. box indicates the size and 
location of the nested frame relative to the graphics container; these values are in micas. 

frameProps are the properties for the frame. 

FrameProps: type ■ . long pointer to FramePropsRec; 

ReadonlyFrameProps: TYPE ■ LONG POINTER TO READONLY FramePropsRec; 

FramePropsRec: type » record [ 
brush: Brush, 
fixedShape: bool, 

margins: array Side of long cardinal, 

captionContent: array Side of oocinterchang«oefs.Caption, 

sparel: LONG cardinal]; 

Brush: TYPE ■ record [ 

wthbrush: long cardinal, 
stylebrush: StyleBrush]; 

StyleBrush: TYPE • machine dependent{ 

invisibie(O), soiid(l), dashed(2), dotted(3). double(4), broken(5), (15)}; 

brush describes the properties of the lines that make up the frame. The brush width is in 
micas. The standard brush widths on the property sheet are 35, 71, 106, 141, 176 and 212. 
Note that wthbrush depends on the stylebrush specified: for double borders wthbrush 
should be 3 times the usual width. 

fixedShape indicates whether the frame will expand in a uniform fashion, 
margins are the frame margins, in points. 
Side: type ■ {top, bottom, left, right}; 
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captionContent is an array of captions associated with the frame. Note that the 
captionContent parameter is only meaningful during enumeration, and not during Start or 
Add* routines, since the caption content is added after the frame is created. 

sparel is for future use. 

name and description are the name and description of the graphics frame as it appears in 
the property sheet. 

spareProps is for future use. 

want*CaptionHandie indicates whether the client wants the frame to have the 
corresponding captions. If the client passes true for one of these values, the corresponding 
return value will be non-NiL. The client can then use OocinterchangeDefs routines to add 
text to the caption. Note that the caption must eventually be freed with 
oocint«rchang«o«fs.ReieaseCaption. 

gf h is a handle to the newly created graphics frame. 

StartButton:PROC[ 
h: Handle, 
box: Box, 

buttonProps: ReadonlyButtonProps, 

frameProps: ReadonlyFrameProps, 

wantProgramHandle, 

wantTopCaptionHandle, 

wantBottomCaptionHandle, 

wantLeftCaptionHandle, 

wantRightCaptionHandle: boolean false] 

RETURNS [ 

bfh: Handle. 

buttonProgram: ButtonProgram, 

topCaption, bottomCaption, 

leftCaption, rightCaption: oocint«rchang«o«fs.Caption]; 

StartButton initializes a cusp button as a graphics container, box describes the size and 
location of the cusp button relative to the graphics container h. 

ButtonProps: TYPE ■ long pointer to ButtonPropsRec; 

ReadoniyButtonProps: type ■ long pointer to readonly ButtonPropsRec; 

ButtonPropsRec: type ■ record [ 
name: XString.Reader, 
sparel: LONG cardinal!; 

ButtonProgram: TYPE ■ long pointer to ButtonProgramObject; 

ButtonProgramObject: type; 

buttonProps are the default properties for the button. If the client defaults this parameter, 
StartButton will generate a new unique name for the button. 
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wantProgramHandle specifies whether the client wants to be able to add to the button's 
program. If the client specifies TRUI, and is returned a valid button program handle, then it i 
must later free that handle with a call to ReieaseButtonProgram (see section 75.2.1.7). 
GraphicsInterchangeOefs provides several procedures that the client can use to add data to 
the cusp program; see section 75.2.1.5, AcUiing to a cusp button, for information on these 
procedures. 

All other properties are as described for StartGraphicsFrame. 

75.2.1.2 Setting extra frame properties 

SetExtraAnchoredFrameProps: proc[ 
doc: 0oclnterdiange0«fs.D0Cf 
anchoredFrame : OodntarchangeOefs.1 nstance, 
name, description : xstring.Reader, 
spareProps: long pointer <- nil, 
selections: ExtraAnchoredFramePropsSelections]; 

ExtraAnchoredFramePropsSelections: TYPE « packed array 

ExtraAnchoredFramePropsElementsOFOo€int«r€hangePropsOefs.BooleanFalseDefault,° 

ExtraAnchoredFramePropsElements: type » {narne^ description, spareProps}; 

The client can associate a name and description with an anchored frame by calling 
SetExtraAnchoredFrameProps. doc is the document that contains the anchored frame. Atm^ 
anchoredFrame is the frame in which the client Intends to add a name or description. 
spareProps are for future use and should be left defaulted to nil. selections indicate which 
properties the client intends to add. 

75.2.1.3 Adding geometries to a graphics container 

AddCurve: PR0C[h: Handle, box: Box, curveProps: ReadonlyCurveProps]; 

CurveProps: type • long pointer to CurvePropsRec; 

ReadonlyCurveProps: TYPE a long pointer to readonly CurvePropsRec; 
CurvePropsRec: type ■ record [ 

brush: Brush, 

lineEndNW: LineEnd, 

lineEndSE: LineEnd, 

lineEndHeadNW: LineEndHead, 

lineEndHeadSE: LineEndHead, 

direction: LineOirection. 

piaceNW, placeApex, placeSE, placePeak: Place, 

fixedAngie: bool, 

sparel: long cardinal]; 

LineEnd: TYPE ■ machine dependent { 

f lush(O), square(1 ), round(2), arrow(3), (7)}; 
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LineEndHead: TYPE ■ machine dependent { 
none(OK h1(1), h2(2), h3(3), (1 5)}; 

UneOirection: type ■ machine dependent { 
WE{OK NS(1), NwSe(2), SwNe(3)}; 

AddCurve adds the curve described by curveProps to the specified graphics container, box 
specifies the location of the curve relative to the graphics frame. If box.dims is smaller 
than the curve, only that part of the curve that fits within box.diins will be displayed. 

brush indicates the line properties of the curve; brush is as described earlier for 
StartGraphicsFrame. 

lineEnd* describe the properties of the ends of the curve. lineEndNW describes the end that 
would paint first if the curve is traced clockwise; imeEndSE describes the end that would 
paint last tracing clockwise (Figure 75.1). 




Figure 75. 1 Curve Direction 



If lineEnd s arrow, then lineEndHead describes the type of arrow: hi is the thinnest 
arrowhead; h3 is the thickest as shown in Figure 75.2. If lineEnd narrow, then 
lineEndHead should be none. 



► 


hi 


► 


h2 


► 


h3 



Figure 75.2 Arrowheads 
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direction is ignored; the client should always set this to WEo 

place* defines the curve by specifying its endpoints, apex, and peak. These points are 
relative to box, and not the frame itself. Recall that curves paint clockwise; clients must 
ensure that the NW endpoint appears before the SE endpoint when tracing the curve 
clockwise. Figure 75.3 illustrates these four points for two different curves; the triangle 
marks the apex, the square marks the peak, and the circles mark the endpoints. 



fixedAngie indicates that the curve will maintain its shape when grown or shrunk, spa re 1 
is for future use. 

AddEccentricCurve: proc [ 
h: Handle, 
box: Box, 

eccentricCurveProps : Readonly EccentricCurveProps] ; 

EccentricCurveProps: TYPE ■ long pointer to EccentricCurvePropsRec; 

Readonly EccentricCurveProps: type « 

LONG pointer TO READONLY EccentrlcCurvePropsRec; 

EccentricCurvePropsRec: type ■ record [ 
brush: Brush, 
lineEndNW: LineEnd, 
lineEndSE: LineEnd, 
lineEndHeadNW: LineEndHead, 
llneEndHeadSE: LineEndHead, 
direction: UneOirection, 
piaceNW, placeApex, placeSE: Place, 
eccentricity: cardinal, 
fixedAngie: bool, 
sparel : long cardinal]; 

AddEccentricCurve is just like AddCurve except that the curve is specified by its endpoints, 
apex, and eccentricity, rather than by endpoints, apex and peak. 




Figure 75.3 Defining curves 



eccentricity is a fraction represented by eccentricity / last[caroinal] . This allows the 
highest possible precision for eccentricities between 0 and 1. 
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Add El I ipse: proc[ 
h: Handle, 
box: Box, 

eilipseProps: ReadonlyEllipseProps]; 

EllipseProps: TYPE ■ long pointer to EllipsePropsRec; 

ReadonlyEllipseProps: type ■ long pointer to readonly EIHpsePropsRec; 

EllipsePropsRec: type ■ record [ 
brush: Brush, 
shading: Shading, 
fixedShape: bool, 
sparel : long cardinal] ; 

AddEllipse adds an ellipse to the specified graphics container, box.dims determine the size 
and shape of the ellipse; box.place determines its location relative to the container h. 

Shading: TYPE ■ record [gray: Gray, textures: Textures]; 

Gray: TYPE « machine dependent { 

none(0), gray25(1), gray50(2), gray75(3), black(4), (1 5)}; 

Textures: TYPE « packed array Texture op boolean; 

Texture: TYPE ■ MACHINE dependent { 

verticai(O), horizontal(l), nwse(2). swne(3), polkadot(4), (11)}; 

Within the EilipseProps, brush describes the ellipses' border, and shading describes its 
interior. The shading of the interior can be 25%, 50%, or 75% gray or solid black; the 
texture can be horizontal, vertical, or diagonal lines, or dots. fixedShape has the same 
meaning for all shapes: it indicates that the proportions of the object will not change when 
the user grows or shrinks it. sparel is for future use for all shapes. 

AddLine: proc [ 
h: Handle, 
box: Box, 

lineProps: ReadonlyLineProps]; 

LineProps: TYPE ■ long pointer to Li nePropsRec; 

ReadonlyLineProps: type ■ long pointer to readonly LinePropsRec; 

LinePropsRec: type ■ record [ 
brush: Brush, 
lineEndNW: LineEnd, 
lineEndSE: LineEnd, 
lineEndHeadNW: LineEndHead, 
lineEndHeadSE: LineEndHead, 
direction: LineOirection, 
fixedAngie: bool, 
sparel: long cardinal]; 
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AddLine adds a line to the graphics container h. box describes the bounding box of the line. 
LineProps are all as described above for curves. 

AddPiesiice: proc [ 
h: Handle, 
box: Box, 

piesliceProps: ReadoniyPiesiiceProps]; 

PiesiiceProps: TYPE ■ long pointer to PiesiicePropsRec; 

ReadoniyPiesiiceProps: type ■ long pointer to readonly PiesiicePropsRec; 

PiesiicePropsRec: type ■ record ( 
brush: Brush, 
shading: Shading, 
center, start, stop: Place, 
sparel : LONG CARDINAL]; 

AddPiesiice adds a pieslice object to the graphics container h. box describes the bounding 
box of the pieslice. PiesliceProps are ail as described above for ellipses, center, start, and 
stop are all relative to Isox.piace. The arc of a pieslice goes from start to stop in a clockwise 
direction. Ohly brush styles of none and solid are supported. Ail the pieslice properties 
and operations are currently defined in GraphicslnterchangeExtra30efs. 



AddPoint: PROC[ 
h: Handle, 
box: Box, 

pointProps : ReadoniyPoi ntProps] ; 

PointProps: TYPE ■ long pointer to PointPropsRec; 

ReadoniyPointProps: type ■ long pointer to readonly PointPropsRec; 

PointPropsRec: type ■ record [ 
wthbrush: long cardinal, 
pointStyle: PointStyle, 
pointFill: PointFill, 
sparel : LONG cardinal]; 

PointStyle: type ■ machine dependent {round(0),square(1),triangle(2),cross(3), (255)}; 

PointFill: TYPE a machine dependent {solid(0),hoilow(1), (255)}; 



AddPoint adds the point described by box and pointProps to the graphics container h. 
wthbrush is in micas. pointStyle and pointFill are as shown in the Point object property 
sheet. 



AddRectangle: proc[ 
h: Handle, 
box: Box, 

rectangieProps: ReadonlyRectangleProps]; 
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RectangieProps: type ■ long pointer to RectangiePropsRec; 

ReadoniyRectangieProps: type ■ long pointer to readonly RectangiePropsRec; 

RectangiePropsRec: type ■ record [ 
brush: Brush, 
shading: Shading, 
fixedShape: bool, 
sparel: LONG cardinal]; 

AddRectangle adds the rectangle specified by box to the graphics container h. Rectangle 
properties are as described aisove for ellipses. 

AddTriangle: proc [ 
h: Handle, 
box: Box, 

triangleProps: ReadonlyTriangieProps]; 

TriangieProps: type ■ long pointer TO TriangiePropsRec; 

ReadonlyTriangieProps: type ■ 

LONG POINTER TO READONLY TrianglePropsRec; 

TriangiePropsRec: TYPE » record [ 
brush: Brush, 
shading: Shading, 

piacel, piace2, places : Place, - corners of triangle 
fixedShape: bool, 
sparel: LONG cardinal]; 

AddTriangle adds a triangle to the graphics conainter h. brush and shading are as 
described for ellipses; placel , place2, and placei are the corners of the triangle, relative to 
box. The triangle is added to h at box.place. 

75.2.1.4 Adding frames to a graphics container 

The following Add* routines add various t3rpes of frame objects to the graphics container. 
Each of these routines has a parameter of type FrameProps that describes the frame, and 
want*CaptionHandle parameters that determine the captions for that frame. These 
parameters are as described in section 75.2.1.1, StartGraphicsFrame. 

AddBitmap: proc [ 
h: Handle, 
box: Box, 

bitmapProps: ReadonlyBitmapProps, 
frameProps: Readonly FrameProps, 
wantTopCaptionHandle, 
wantBottomCaptionHandle, 
wantLeftCaptionHandle, 
wantRightCaptionHandle: boolean <- false] 

RETURNS [ 
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topCaption, bottomCaption, 

ieftCaption, rightCaption: Dodnterchang«Oefs.Caption]; 

bitmapProps describes a bitmap frame. bitmapProps largely correspond to the properties 
that the user sees in the property sheet. 

BitmapProps: type ■ long pointer to BitmapPropsRec; 

ReadonlyBitmapProps: TYPE ■ long pointer to readonly BitmapPropsRec; 

BitmapPropsRec: type ■ record [ 
opaque: boolean, 
xOffset, yOffset: long integer, 
printFiie: xstring.ReaderBody, 
dispiaySource: BmOispiay, 
scaiingProps: BitmapScaiingProps, 
sparel : long cardinal]; 

opaque specifies whether the bitamp is opaque or transparent. xOffset and yOffset 
control the position of the bitmap within the bitmap frame. Setting both to 0 will position 
the bitmap flush in the upper lefl-hand comer. These values are in units of 1/72 inch. 

printFiie is the source for the bitmap to print. This is usually the same as the display 
source, but the client may specify a file name as an alternate print source if desired. 

BmDispiay: type ■ record [ 

SELECT type FROM 

internal ■ > [bm: long pointer TO BitmapOata], 
file ■ > [name: xstring.ReaderBody], 
endcase]; 

The source for the displayed bitmap is in one of two locations: either internal (the bits are 
copied into the document), or in a file on the desktop. 

BitmapData: TYPE ■ RECORD [ 

signature: integer <- bmSignature, - do not use any other value 

xScale: interpress.Rationai, 

yScale: Interpress.Rationai, 

xOim: cardinal, - # of bits wide 

yOim: cardinal, ~ # of bits tall 

bpl: cardinal, - Bits Per Line = ((xDim + 15)/ 16)* 16 

pages: NSS«gm«fit.PageCount, 

bits: PACKED ARRAY [0..0) OF Environm«nt.Byte]; 

bmSignature: integer ■ 23456; 

The actual bitmap is described by a BitmapData record, signature is a validity check for 
the bitmap. If a bitmap signature is anything but bmSignature, the implementation will 
not recognize it as a valid bitmap. 

xScale and yScale specify the bitmap scale. At present, the only scale that is supported is 
72 spots per inch, so the client should always set xScale and yScale to [254, 720,000]. ( The 
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default unit for an interpress-Rational is meters; converting inches to meters yields 720,000 
spots per 254 meters, since 1 inch = 2.54 cm.) 

xOim and yOim describe the size of the bitmap, bpi is the width of the bitmap, roimded to 
the nearest word boundary. 

pages is the number of pages that the bitmap occupies, and bits is the actual bitmap. 

BitmapScaiingProps: type ■ record [ 
SELECT type: *from 

printerResolution ■ > [resolution: cardinal], 
fixed a > [ 

horizontalAlignment: {center, right, left}« 

verticalAlignment: {center, bottom, top}, 

scalingPercentage: cardinal [0..1024)], 
automatic « > [shape: {similar, f itiUp}], 

other « > [sparel : packed array [2..15) of [0..1], spare2: cardinal], 
endcase]; 

scaiingProps specifies one of the three bitmap scaling modes: automatic, fixed or 
printerResolution. The client will generally default the mode to automatic with shape • 
similar; this ensures that the bitmap will be automatically magnified/shrunk to fit just 
inside the bitmap frame until either the vertical or horizontal edge reaches the frame's 
edge. If fillUp is specified, the vertical and horizontal scaling factors are individually 
determined so that the bitmap completely fills the frame. 

The fixed mode requires the client to control the bitmap's alignment (by Alignment 
parameters) and scaling (by Scale parameter). The scalingPercentage allows the client to 
shrink or magnify the bitmap. A scalingPercentage value of 100 means that the bitmap 
should be displayed and printed the same size as the original. A value of 50 means that the 
bitmap is shrxmk to one half both vertically and horizontally. scalingPercentage must be 
in the range [1..1000]. 

printerResolution indicates the resolution of the printer; typical values are: 72, 75, 150, 
200, and 300. Other values can be specified and must be the number of spots per inch. 

AddFormField: proc[ 
h: Handle, 
box: Box, 

f ieidProps : Docint«rchang«PropsD«fs.Readonly FieldProps, 

frameProps: ReadonlyFrameProps, 

paraProps: oocinterchang«Prop$D«fs.ReadonlyParaProps 4- nil, 

fontProps: Do€interchangePropsO«fs.ReadonlyFontProps 4-nil, 

expandRight, expandBottom: bool^-false, 

wantFieldHandle, 

wantTopCaptionHandle, 

wantBottomCaptionHandle, 

wantleftCaptionHandle, 

wantRightCaptionHandle: boolean 4- false] 

RETURNS [ 

field: OocinterchangeOefs.Field, 



75-13 



75 GraphicsInterchangeDefs 



topCaption, bottomCaption, 

ieftCaption, rightCaption: oocinterchangeOefsXaption]; 

AddFormFieid adds the specified field to h at the location box.piace. A more flexible 
version of this operation is now supported— see AddFormFieldX below. 

If the client speclHes wantFieldHandle = true, AddFormField will return a 
Ooclnt«rchang«o«fs.Fi«id; the client must eventually free this field with a call to 
oocint«rchang«o«fs.ReleaseField. To add information to the field, the client should use the 
facilities of DoclnterchangeDefs. 

AddFormFieldX: proc[ 
h: Handle, 
box: Box, 

f ieldProps : OodnterchangeProp$Oefs.Readonly FieldProps, 

frameProps: ReadonlyFrameProps, 

textFrameProps: ReadonlyTextFrameProps, 

paraProps: oocint«r€hang«Propso«fs. Readonly Pa raProps <-nil, 

fontProps: 0odnterehang«PropsO«fs.ReadonlyFontProps ^NIL, 

wantFieldHandle, 

wantTopCaptionHandle, 

wantBottomCaptlonHandle, 

wantLeftCaptionHandie, 

wantRightCaptionHandle: boolean 4- false] 

RETURNS [ 

field: OocinterchangeOefs.Field, 
topCaption, bottomCaption, 
leftCaption, rightCaption: Do€interchangeOefs.Caption]; 

This operation is currently in GraphicslnterchangeExtralDefs (see older form above). 

Addfmage: proc[ 
h: Handle, 
box: Box, 

imageProps: Readonly I mageProps, 
frameProps: ReadonlyFrameProps, 
wantTopCaptionHandle, 
wantBottomCaptlonHandle, 
wantLeftCaptionHandie, 
wantRightCaptionHandle: boolean false] 

RETURNS [ 

topCaption, bottomCaption, 

leftCaption, rightCaption: oocinter€hanga06fs.Caption]; 

ImageProps: TYPE ■ long pointer to I magePropsRec; 

ReadonlylmageProps: TYPE ■ long pointer to readonly ImagePropsRec; 

ImagePropsRec: type • record [ 
name: XString.Reader, 
sparel: LONG cardinal]; 
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Addlmage adds an image frame to the specified graphics container. 

AddTabie: proc [ 
h: Handler 
box: Box, 

table: oociiitcrduing«D«fs.lnstance. 
frameProps: ReadonlyFrameProps, 
wantTopCaptionHandle, 
wantBottomCaptionHandle, 
wantLeftCaptionHandle, 
wantRightCaptionHandle: boolean 4- false] 

RETURNS [ 

topCaption, bottomCaption, 

ieftCaptlon, rIghtCaptlon: Docint«rchang«o«fs.Captlon]; 

AddTabie adds a table frame to the graphics container h. table should be the instance 
returned from Tabi€interchang«Defs.FinishTable. This operation is currently defined in 
GraphicstnterchangeExtra2Defs. 

AddTextFrame: proc[ 
h: Handle, 
box: Box, 

frameProps: ReadonlyFrameProps, 
textFrameProps: ReadonlyTextFrameProps, 
wantTextHandle, 
wantTopCaptionHandie, 
wantBottomCaptionHandle, 
wantLeftCaptionHandie, 
wantRightCaptionHandle: boolean ^ false] 
returns [ 

text: T«xtlnterchangeOefs.Text, 

topCaption, bottomCaption, 

leftCaptlon, rightOiption: Docintardiange.Caption]; 

TextFrameProps: type ■ long pointer to TextFramePropsRec; 

ReadoniyTextFrameProps: type ■ 

LONG pointer to READONLY TextFramePropsRec; 

TextFramePropsRec: type ■ record [ 

expandRight, expandBottom, transparent: bool, 
tFrameProps : Textint«rchang«D«fs.TFramePropsRec. 
sparel: LONG cardinal]; 

AddTextFrame adds a text frame to the specified graphics container. If the client specifies 
wantTextHandle = true, it will return a handle to a text frame. The handle may then be 
used to add text to the central area of the frame. 
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75.2.1.3 Adding to a cusp button 

The following routines allow the client to add textual information to a cusp button 
program. 

AppendCharToButtonProgram: proc[ 
to: ButtonProgram, 
char: xOrar.Character, 

f OntPropS : OoclnterchangePropsO«fs.Readoniy FontPropS 4- NIL. 

nToAppend: cardinal 1]; 

Add a character to the button program. nToAppend is the number of copies of the 
character to be added; fontProps are the properties of the character. 

AppendNewParagraphToButtonProgram: proc [ 
to: ButtonProgram, 

paraProps: oo€int«rchangePropso«fs.ReadonlyParaProps ^-nil, 
fontProps: oocint«rchang«PropsO«fs.ReadoniyFontProps nil, 
nToAppend : cardinal 1 ]; 

Add a new paragraph character with specified properties to the button program. 

AppendTextToButtonProgram: proc( 
to: ButtonProgram, 
text: xstring.Reader, 

textEndContext: xistringXontext, 

fontProps: oocinterchangePropsOefs.ReadoniyFontProps 4- nil]; 

Add a string with specified properties to button program. For efficiency, the client should 
include textEndContext if known. Do not append newParagraph characters [set: 0, code: 
35B] with this operation-use AppendNewParagraphToButtonProgram for that. 

75.2.1.6 Adding miscellaneous graphics 

AddOther: proc[ 
h: Handle, 
box: Box, 

instance:Do€int0rchangeOefs.lnstance]; 

AddOther is provided to allow addition of charts and other as yet undefined objects. For 
information on charts, see ChartOatalnstaliDefs. 

75.2.1.7 Release routines 

ReleaseButtonProgram: proc [ 

bpPtr: LONG pointer TO ButtonProgram]; 

ReleaseButtonProgram releases the handles obtained from AddButtonProgram. Like 
Mesa's FREE operator, this routine take a pointer to the object to be freed, and sets the 
handle itself to nil. Thus, sifter a call to ReleaseButtonProgram, ButtonProgram will be nil. 
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73.2.1.8 Finish routines 

When everything has been added to a graphics container, the client should call a Finish 
routine. 

FinishButton: proc [bfh: Handle]; 

FinishCluster: proc [ch: Handle]; 

FinishGraphics: proc [h: Handle] 

RETURNS [graphics: Docint«rchang«o«fs.lnstance]; 

FinishGraphlcsFrame: proc [gfh: Handle]; 

bfh, ch, h, and gfh are the handles obtained from the corresponding Start routines. The 
client will typically pass the Oocint«rchangeO«fs.instance returned by FinishGraphics to 
oo<int«rchang«oefs.AppendAnchoredFrame. 

75.2.2 Reading graphics 

To read the contents of a graphics frame, the client should call Enumerate. Enumerate, 
takes as parameters a graphics container and a list of call back procedures, one for each of 
the. kinds of items that might be in the graphics container. Enumerate will proceed 
through the graphics container, calling the appropriate procedure for each item that it 
encounters. 

Each enumeration procedure takes parameters that describe the properties of the object. 
These properties are temporary, and will be destroyed afber the client procedure returns. If 
the client wishes to save any of these properties, it must explicitly copy them. 

Client EnumProcs should not call any Release* routines on anything passed them as a 
parameter. The Enumerator always releases containers after calling each EnumProc. 

In the case of a cusp button, cluster, or nested gpraphics frame, the client can recursively 
call Enumerate to get the contents of the nested frame. There are also related 
enumerators, T«xtinterchang«D«fs.EnumerateText and EnumerateButtonProgram, that 
enumerate the contents of a text frame and a cusp button, respectively. 



76.2.2.1 Enumerate and its callbacks 

Enumerate: proc[ 

doc: DoclntarchangeDefs.Ooc« 
graphicsContainer: DocinterchangeOefs.lnstance, 
procs: EnumProcs, 
dientOata: long pointers nil] 
returns [dataSkipped: boolean]; 

EnumProcs: TYPE ■ long pointer to EnumProcsRecord; 

EnumProcsRecord: TYPE ■ record! 
bitmapProc: BitmapProc ^-nil. 
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buttonProc: ButtonProc <- nil, jg^ 

dusterProc: ClusterProc <- nil, 

curveProc: CurveProc ^^-nil, 

ellipseProc: EllipseProc4-NiL, 

formFieidProc: FormFteldProc4-NiL, 

frameProc: FrameProc4-NiL, 

imageProc: ImageProc 4-nil, 

lineProc: LineProc 4-nil, 

otherProc: OtherProc 4-nil, 

pointProc: PointProc4-NiL. 

rectangleProc: RectangieProc4-NiL, 

textFrameProc: TextFrameProc nil, 

triangleProc: TriangieProc nil] ; 



To enumerate an anchored graphics frame as a graphics container, pass the 
anchoredFrame parameter of the DocinterchangeOefs.AnchoredFrameProc into Enumerate, 
not the content parameter. See the OoclnterchangeOefs documentation for 
AnchoredFrameProc. 

BitmapProc:TYPE ■ PR0C[ 
ciientData: LONG POINTER, 
box: Box, 

bitmapProps: Readonly BitmapProps,. 
frameProps: ReadoniyFrameProps] 
returns [stop: boolean false]; 

ButtonProc: type ■ proc [ 
ciientData: long pointer, 
gra ph i csContai ner: DocinterchangeOef s.l nstance, 
box: Box, 

buttonProps: ReadoniyButtonProps, 
frameProps: ReadoniyFrameProps, 
buttonProgram: ButtonProgram] 
returns [stop: boolean false]; 

ClusterProc: type ■ proc [ 
ciientData: long pointer, 
graphicsContainer:Docinterchang«o«fs.lnstance, 
box: Box] 

returns [stop: boolean false]; 



CurveProc: TYPE ■ proc[ 
ciientData: long pointer, 
box: Box, 

curveProps: ReadonlyCurveProps] 
returns [stop: boolean <- false]; 

EllipseProc: TYPE ■ proc[ 
ciientData: long pointer, 
box: Box, 



75-18 



Viewpoint Programmer's Manual 



ellipseProps: ReadonlyEilipseProps] 

RETURNS [stop: BOOLEAN <- FALSE]; 

FormFieldProc: type ■ proc [ 

clientOata: long pointer, box: Box. 

fieidProps:Docint«rchang«PropsD«fs.ReadoniyFieidProps. 

frameProps: ReadonlyFrameProps, 

paraProps:Dodnt«rchang«Propso«fs.ReadoniyParaProps« 

fontProps:DocintttrdiangePropsO«fs.ReadonlyFontProps, 

expandRight, expandBottom: bool, 

content: Doclnt«rchang«0«fs.Field] 

returns [stop: boolean false]; 

FrameProc: type ■ proc [ 
clientOata: long pointer, 

graphicsContainer: OoclnterchangeOefsJnstance, 
box: Box, 

frameProps: ReadonlyFrameProps, 
name, description: xstring.Reader, 
spareProps: long pointer] 

RETURNS [stop: BOOLEAN <~ FALSE]; 

imageProc: type a proc [ 
clientOata: LONG POINTER, 
box: Box, 

imageProps: Readonly! mageProps, 
frameProps: ReadonlyFrameProps] 

RETURNS [stop: BOOLEAN <- FALSE]; 

LineProc: type » proc[ 

clientOata: long pointer, 
box: Box, 

lineProps: Readonly Li neProps] 
RETURNS [stop: boolean false]; 

OtherProc: type ■ proc [ 
cl ientOata : long pointer, 
box: Box, 

instance: DocinterchangeOefs.lnstance, 

objectType: OtherObjectType] 

RETURNS [stop: BOOLEAN <~ FALSE]; 



OtherObjectType: TYPE « machine dependent { 

illusFrame(O), barchart, linechart, piechart, piesiice, table, equation, 
firstAvaiiable, lastAvailabie(255)}; 

Although data driven charts are not yet fully supported by any Interchange interface, it is 
possible to enumerate the graphic components of one. In the OtherProc, simply call 
Enumerate on the instance when it is a chart, and the appropriate procedures will be called 
for its contained graphic objects. Think of it as a cluster. 
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PointProc: TYPE ■ proc[ 
ciientData : long pointer, 
box: Box, 

pointProps: ReadoniyPointProps] 

RETURNS [stop: BOOLEAN <~ FALSE]; 

RectangieProc: TYPE ■ proc[ 
ciientData: long pointer, 
isox: Box. 

rectangleProps: ReadoniyRectangieProps] 
returns [stop: boolean <- false]; 

TextFrameProc: type ■ proc ( 
ciientData: long pointer, 
box: Box, 

frameProps: ReadoniyFrameProps, 
textFrameProps: ReadonlyTextFrameProps, 
content: T«xtlnter€hang«0«fs.Text] 
RETURNS [stop: BOOLEAN ^ FALSE]; 

TriangleProc: type ■ proc [ 
ciientData: LONG POINTER, 
box: Box, 

triangleProps: ReadonlyTriangieProps] 

RETURNS [stop: BOOLEAN 4-FALSE]; jii^ 



GetExtraAnchoredFrameProps: proc[ 
doc: OoclnterchangeOefs.DOC, 
anclioredFrame:oocinterchangeOefs.lnstance, 
spareProps: long pointers- nil, 
zone: uncounted zone] 

RETURNS [name, description: xstring.ReaderBody]; 

The name and description properties can be retrieved from an anchored frame with 
GetExtraAnchoredFrameProps. spareProps and zone are for future use. The returned 
values are not allocated from zone and so are read-only; the client should not attempt to 
call xstring.FreeReaderBytes on them. Within a oocint«rchang«o«fs.AnchoredFrameProc the 
client should pass the anchoredFrame parameter to GetExtraAnchoredFrameProps, rather 
than the content parameter. 

GetExtraFormFieldProps: proc [contentOfForm Field: DocintarchangeOefs.Fieid] 
RETURNS [textFrameProps: ReadonlyTextFrameProps]; 

This operation returns a readonly pointer to the text frame properties of a form field. 
GetExtraFormFieldProps may only be called from within a FormFieldProc. The enumerator 
owns the storage of all the returned properties. GetExtraFormFieldProps is currently 
defined in GraphicslnterchangeExtralDefs. 

GetNestedTableProps: proc [ 
doc: OoclnterchangeOefs.DOC, 



75.2.2.2 Getting extra properties 
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instance: OocinterchangeOefs.lnstance, 

frameProps: FramePropsl 

RETURNS [content: Ooclnter€hangeOefs.lnstance]; 

GetNestedTabieProps fills in frameProps with the frame props of the nested table frame 
and returns content. May be called only within an OtherProc during an enumeration, and 
the instance passed to GetNestedTableProps must be the same as the one passed to the 
OtherProc. The entries of the frameProps.captionContent are readonly and are owned by 
the enumerator, so they are valid only during that call to the OtherProc. Do not call 
Docint«rdiang«o«fs.ReieaseCaption on any of them. Use Tableint«rchangeOefs.EnumerateTable 
[content, ...] to obtain the rest of the table's properties. GetNestedTableProps is currently 
defined in GraphicslnterchangeExtra2Defs. 

GetPiesliceProps: proc [ 

doc: 0oclnterchange0«fs.DOC, 
instance: Docinter€hangeOttfs.lnstance, 
piesliceProps: PlesliceProps]; 

GetPiesliceProps fills in piesliceProps with the properties of the pieslice. May be called 
only within an OtherProc when the object is a pieslice. GetPiesliceProps is currently 
defined in GraphicslnterchangeExtraSDefs. 

75^2.3 Enumeratini; cusp button programs 

EnumerateButtonProgram: PROc[ 
buttonProgram: ButtonProgram, 
procs: ButtonProgramEnumProcs, 
cl i entOata : long pointer *~ nil] 
RETURNS [dataSkipped: boolean]; 

ButtonProgramEnumProcs: type ■ 

LONG pointer TO ButtonProgramEnumProcsRecord; 

ButtonProgramEnumProcsRecord: TYPE ■ record [ 

newParagraphProc: Oocinttrchangeo«fs.NewParagraphProc <-nil, 
textProc: Dodnt«rchangaO«fs.TextProc 4- nil]; 

EnumerateButtonProgram enumerates the contents of buttonProgram, calling the client- 
supplied procs as appropriate. ciientData is passed to each of the call-back procedures 
during enumeration. 

75.2.3 Constants 

nuilBitmapProps: BitmapPropsRec ■ [ 
opaque: true, 
xOffset: 0, 
yOffset: 0. 

printFile: xstring.nullReaderBody, 
displaySource: nuilBmOisplay, 
scalingProps: nullBitmapScalingProps, 
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sparel : 0]; 

nuilBmOisplay: BmOisplay « [mternal[bm: nil]]; 

nullBitmapScalingProps: BitmapScalingProps ■ [automatkCshape: similar]]; 

nuilButtonProps: ButtonPropsRec ■ [name: nil, sparel : 0]; 

nullCurveProps: CurvePropsRec ■ [ 
brush: [0, solid], 
lineEndNW: flush, 
lineEndSE: flush, 
lineEndHeadNW: none, 
lineEndHeadSE: none, 
direction: WE, 
piaceNW: [0,0], 
piaceApex: [0,0], 
piaceSE: [0, 0], 
placePeak: [0, 0], 
fIxedAngle: false, 
sparel : 0]; 

nuilEccentrfcCurveProps: EccentricCurvePropsRec ■ [ 
brush: [0, solid], 
lineEndNW: flush, 
lineEndSE: flush, 
lineEndHeadNW: none, 
lineEndHeadSE: none, 
direction: WE, 
placeNW:[0,0], 
placeApex: [0,0], 
piaceSE: [0, 0], 
eccentricity: 0, 
fixedAngie: false, 
sparel : 0]; 

nullEllipseProps: EtIipsePropsRec ■ [ 
brush: [0, solid], 
shading: [none,ALL[FALSE]], 
fixedShape: false, 
sparel : 0]; 

nullFrameProps: FramePropsRec ■ [ 
brush: [0, solid], 
fixedShape: false, 
margins: all[0], 
captionContent: all[nil], 
sparel : 0]; 

nulllmageProps: ImagePropsRec ■ [name: nil, sparel :0]; 

nullLineProps: LinePropsRec ■ [ 
brush: [0, solid]. 
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lineEndNW: flush, 
lineEndSE: flush, 
HneEndHeadNW: none, 
lineEndHeadSE: none, 
direction: WE, 
f IxedAngle: false, 
sparel: 0]; 

nullPiesliceProps: PieslicePropsRec ■ [ 
brush: [2, solid], 
shading: [none, all[false]], 
center: [0, 0], 
start: [0, 0], 
stop: [0,01, 
sparel : 0]; 

nuilPiesiiceProps is currently defined in GraphicslnterchangeExtra3Defs. 

nullPointProps: PointPropsRec ■ [ 
wthbrush: 0, 
pointStyie: round, 
pointFiil: solid, 
sparel : 0]; 

nullRectangleProps: RectanglePropsRec * [ 
brush: [0, solid], 
shading: [none,ALL[FALSE]], 
fixedShape: false, 
sparel : 0]; 

nuilTextFrameProps: TextFramePropsRec ■ [ 
expandRight: false, 
expandBottom: false, 
transparent: false, 

tFrameProps:T«xtinterdiang«Defs.nuilTFrameProps, 
sparel : 0]; 

nullTriangleProps: TrianglePropsRec ■ [ 
brush: [0, solid], 
shading: [none,ALL[FALSE]], 
piacel : [0, 0], 
place2: [0, 0], 
places: [0,0], 
fixedShape: false, 
sparel : 0]; 

75.3 Usage/Examples 

The following code copies anchored graphic and cusp button frames from a source 
document being enumerated to a target document being created. What follows is not a 
complete program; the jumping off point is a DocinterchangeOefs.AnchoredFrameProc. This 
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code fits in with the example code listed in the DoclnterchangeOefs documentation. Some 
of the declarations below are copied from the DoclnterchangeOefs example. 

- Types 

CaptionsHandle: TYPE = long pointer to CaptionsRec; 

CaptionsRec: type s record [tc, be. Ic. rc: OoclnterchangeOefs-Caption]; 

DICtxtHandle: type = long pointer to DICtxt; 

DICtXt: TYPE = RECORD ( 

sourceOoc, targetOoc: OocinterchangeOefs.Doc, 
ignoreNewPar, ignorePFC, aborted, error: booleanI; 
<< A DICtxtHandle is passed as dientData to procs called by 
DoclnterchangeDef5.Enumerate. >> 

GICtxtHandle: type » long pointer to GlCtxt; 

GlCtXt: TYPE a RECORD ( 

h : G raphi csl nterchangeOef s. Hand I e, 
sourceOoc, targetOoc: Ooclnterchange0efs.0oc, 
error: boolI; 

<< A GICtxtHandle is passed as dientData to proa called by 
GraphicslnterchangeDefs.Enumerate, >> 

- Constants 

z: UNCOUNTED zone = BWSZone.shortUfetime; 

- Variables 

giEnumProcsRec: GraphicslnterchangeOefs-EnumProcsRecord <- [ 

bitmapProc: Bitmap, buttonProc: Button, clusterProc: Cluster, curveProc: Curve, 
elllpseProc: Ellipse, formFieldProc: FormField, frameProc: Frame, imageProc: Image, 
lineProc: Line, otherProc: Other, pointProc: Point, rectangleProc: Rectangle, 
textFrameProc: TextFrame, triangleProc: Triangle]; 

giEnumProcs: GraphicslnterchangeOefs-EnumProcs = @giEnumProcsRec; 

< < Called when an anchored frame was encountered in the source document 

Copies the frame and its contents to the target document. > > 
AppendAnchoredFrameToTargetDoc: DoclnterchangeOefs.AnchoredFrameProc s { 

diCtxt: OICtxtHandle a dientData; 

sourceCaptions: CaptionsRec *- [ 

topCaption, bottomCaption, leftCaption, rightCaptionj; 

newCaptions: CaptionsRec; 

IF (diCtxt.aborted <-BaclcgroundProcess.UserAbort(]) THEN { 

BackgroundProcess.ResetUserAbortn; RETURN[stop: true]; }; 
select type from 

graphics = > { 

h: GraphicsInterchangeDefs. Handle *- GraphicslnterchangeOefs.StartGraphics( 

diCtxt. targetOoc]; 
giCtxt: GlCtxt <- [h, diCtxt.sourceOoc, diCtxt. targetOoc, false]; 
gc: OoclnterchangeOefs.lnstance; 
(] GraphicsInterchangeDefs. Enumerate[ 

diCtxt.sourceOoc, anchored Frame, giEnumProcs, ©giCtxt]; 

{ 

nameRB, descriptionRB: XString.ReaderBody; 
gc<- GraphicsInterchangeDefs. FinishGraphics[h]; 
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[nameRB, descriptionRB] 

GraphicslnterchangeDefs.GetExtraAnchoreclFrameProps[ 

doc: diCtxt-sourceDoc, anchoredFrame: anchored Frame, zone: nil]; 
GraphicslnterchangeDefs.SetExtraAnchoredFrameProps[ 

doc: diCtxt-targetDoc, anchoredFrame: gc, name: ©nameRB, 

description: ©descriptionRB, 

selections: [name: true, description: true, spareProps: false]]}; 
I, newCaptlons.tc, newCaptions.bc, newCaptionsJc, newCaptions.rc] 

OoclnterchangeOefs.AppendAnchoredFrame( 

to: diCtxt.targetOoc, type: graphics, 

anchored FrameProps: anchoredFrameProps, 

content: gc, wantTopCaptionHandle: topCaption # nil, 

wantBottomCaptionHandle: bottomCaption # nil, 

wantLeftCaptionHandle: leftCaption # nil, 

wantRightCaptionHandle: rightCaption # nil, 

anchor FontProps: anchorFontProps ! 

DoclnterchangeOefs. Error s > { 

diCtxt.error<-TRUE; stop <- true; continue}]; 
IF 'diCtxt. error then FilllnFrameCaptions[@sourceCaptions, ©newCaptions]; 
}; -graphics 
cuspButton « > { 

bProps: GraphicslnterchangeDefs.ButtonPropsRec; 
bProgSource: GraphlcslnterchangeOefs.ButtonProgram 

ButtonlnterchangeDefs.ButtoninfoForAnchoredFrame[ 

diCtxt.sourceDoc, anchoredFrame, ©bProps, z]; 
bProgTarget: GraphlcsinterchangeOefs.ButtonProgram; 
h: GraphicslnterchangeDefs. Handle; 
glCtxt: GlCtxt; 

bProcs: GraphicslnterchangeDefs.ButtonProgramEnumProcsRecord [ 
newParagraphProc: Append NewParToProg, textProc: AppendTextToProg]; 

AppendNewParToProg: DoclnterchangeOefs. NewParagraphProc = { 
GraphicslnterchangeDefs.AppendNewParagraphToButtonProgram[ 

bProgTarget, paraProps, fontPropsJ; 
}; -AppendNewParToProg 

AppendTextToProg: DoclnterchangeDefs.TextProc = { 
GraphicslnterchangeDefs.AppendTextToButtonProgram[ 

bProgTarget, text, textEndContext, fontPropsj; 
}; - AppendTextToProg 

[h, bProgTarget] <-ButtonlnterchangeDefs.StartButton( 

dlCtxt-targetDoc, ©bProps, (bProgSource # nil)]; 
[] <- GraphicslnterchangeDefs. EnumerateButtonProgramt 

bProgSource, ©bProcs]; 
GraphicslnterchangeDefs. ReleaseButtonProgram[@bProgTarget]; 
ButtonlnterchangeDefs.ReleaseReadOnlyButtonProgram[@bProgSource]; 
giCtxt «- [h, diCtxt.sourceDoc, diCtxt.targetDoc, false]; 
[] <~ GraphicslnterchangeDefs. Enumerate[ 

diCtxt.sourceDoc, anchoredFrame, glEnumProcs, ©giCtxt]; 
(, newCaptions.tc, newCaptions.be, newCaptions.lc, newCaptions.rc] <- 

OoclnterchangeDefs.AppendAnchoredFrame[ 

to: dlCtxt.targetDoc, type: cuspButton, 

anchoredFrameProps: anchoredFrameProps, 

content: ButtonlnterchangeDefs,FinishButton[h], 

wantTopCaptionHandle: topCaption # nil. 
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wantBottomCaptionHandle: bottom Caption # nil, 
wantLeftCaptionHandie: leftCaption # nil, 
wantRightCaptionHandle: rightCaption # nil, 
anchorFontProps: anchorFontProps ! 
OocinterchangeOefs. Error « > { 
dlCtxt.error <-true; stop true; continue}]; 
IF 'diCtxt.errorTHEN FililnFrameCaptions(@sourceCaptions, ©newCaptions]; 

}; 

enocase; 
}; —AppendAnchoredFrame 

< < Called when a bitmap frame was encountered while enumerating the contents 
of a graphics container. > > 

Bitmap: GraphicsinterchangeOefs.BitmapProc = { 

ctxt: GICtxtHandle s dientOata; 

sourceCaptions: CaptionsRec <— ( 

frameProps.captionContent(topl, frameProps.captionContent[bottom], 
frameProps.captionContent(left], fram«Prop$.captionContent[right]]; 

newCaptions: CaptionsRec; 

[newCaptionSotc, newCaptions. be, newCaptionsJc, newCaptions.rc] 
Graphics! nterchangeOefs-AddBitmapC 
ctxt.h, box, bItmapProps, frameProps, sourceCaptions.tc # nil, 
sourceCaptions.bc # nil, sourceCaptionsJc # nil, sourceCaptions.rc # nil]; 

Fill lnFrameCaptions[@sourceCaptions, ©newCaptions]; 

}; -Bitmap 

< < Called when a Cusp button was encountered while enumerating the contents 
of a graphics container. >> 

Button: GraphicslnterchangeDefs-ButtonProc = { 
ctxt: GICtxtHandle = clientData; 
bfh: GraphlcslnterchangeDefs-Handle; 
newProgram: GraphicsInterchangeDefs. ButtonProgram; 
bpProcs: GraphicslnterchangeDefs-ButtonProgramEnumProcsRecord «- [ 

newParagraphProc : Append NewParToProgram, 

textProc: AppendTextToProgramJ; 
newCtxt: GlCtxt; 
sourceCaptions: CaptionsRec *- [ 

frameProps.captionContentftop], frameProps.captionContent(bottoml, 

frameProps.captionContent(left], frameProps.captionContent(rightl]; 
newCaptions: CaptionsRec; 

AppendNewParToProgram: OocinterchangeOefs. NewParagraphProc = { 
GraphicslnterchangeOefs.AppendNewParagraphToButtonProgram[ 

newProgram, paraProps. fontProps]; 
}; "AppendNewParToProgram 

AppendTextToProgram: DoclnterchangeOefs-TextProc = { 
Graphic$lnterchangeOefs.AppendTextToButtonProgram[ 

newProgram, text, textEndContext, fontProps]; 
}; "AppendTextToProgram 

[bfh, newProgram, newCaptions.tc, newCaptions.be, newCaptions.lc, 
newCaptions. re] <- 

GraphicslnterchangeOefs.StartButton[ 

ctxt.h, box, buttonProps, frameProps, buttonProgram # nil, 

sourceCaptions.tc # nil, sourceCaptions.bc # nil, sourceCaptions.lc # nil. 
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sourceCaptions.rc # nil]; 
newCtxt <r- [bfh, ctxtsourceOoc, ctxt.targetDoc, false]; 
[] GraphicslnterchangeDefs.Enumerate( 

ctxt.sourceDoc, graphicsContainer, giEnumProcs, ©newCtxtJ; 
GraphicslnterchangeOefs.PinishButton[bfh]; 
[] GraphicslnterchangeOefs-EnumerateButtonProgramt 

buttonProgram, ©bpProcs]; 
GraphicsinterchangeOefs.ReieaseButtonPrograin[@newProgram]; 
FilllnFrafneCaptions[@sourceCaptions, ®newCaptions]; 
}; -Button 

< < Called when a duster was encountered while enumerating the contents 

of a graphics container. > > 
Custer: GraphicslnterchangeOefs.ClusterProc = { 

ctxt: GICtxtHandle = clientOata; 

ch: GraphicslnterchangeOefs-Handle = 

GraphicslnterchangeOefs.StartCluster[ctxt.h, box]; 

newCtxt: G ICtxt <- [ch, ctxt.sourceOoc, ctxt.targetOoc, false] ; 

[] GraphicslnterchangeDefs.Enumerate[ 

ctxt.sourceOoc, graphicsContainer, giEnumProcs, OnewCtxtj; 

GraphicslnterchangeOefs.FinishCiuster[ch]; 

}; -Ouster 

CopyColumnlnfo: proc [ 

source: Table!nterchangeOefs.Columnlnfo, zone: uncounted zone] 
RETURNS [new: TabieinterchangeOefsXolumnlnfo] s { 
new 4- zone.NEvy[TabielnterchangeOefs .CoiumnlnfoSeq[source.length]]; 
FOR i: CARDINAL IN [O..source.length) do 
new[i] ♦-sourceOl; 
new(i].headerEntryRec.content <- [ 

write(FilllnText, @source{i].headerEntryRec.content]]; 
IF source[i].subco(umninfo # nil then 

new[il.subcolumnlnfo ^ CopyColumnlnfo[source[il.subcolumnlnfo, zone]; 
endloop; 
}; - CopyColumnlnfo 

CopyRowContentlnfo: proc [ 

source: TablelnterchangeDefs-RowContent, zone: uncounted zone] 

returns [new: TablelnterchangeOefs.RowContent] = { 

new 4- zone.NEW[TabielnterchangeOefs .RowContentSeq[source.iength]]; 

new.topMargin <- source.topMargin; 

new.bottomMargin <- source, bottom Margin; 

new.line 4-source.line; 

new.verticalAiignment <~ source. verticalAlignment; 
for i: CARDINAL IN [O..source.length) do 
new.rowdata[i] source.rowdata[i]; 

new.rowdataiij.content [write[FilllnText, @source[i].content]]; 
IF sou rce.rowdata(il. sub Rows # nil then { 
new.rowdata[i].subRows *- zone.NEw[ 

TabieinterchangeOefs.SubRowsRec[source.rowdata[i].subRows.length]]; 
new,rowdata(il.subRows.length «-source.rowdata[i].subRows.length; 
FORj: CARDINAL IN [0..source.rowdata[i].subRows.length) do 
new.rowdata(i].subRows.rows[]] <- CopyRowContentlnfo[ 

sou rce . rowdata [i ] . su bRows. rows[j ] , zone] ; 
endloop; 
}; -hadsubrows 
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ENOLOOP; 

}; - CopyRowContentlnfo 

< < Called when a curve was encountered while enumerating the contents 
of a graphics container. >> 

Curve: GraphicsinterchangeOefs.CurveProc = { 
ctxt: GiCtxtHandle » dientOata; 

GraphicslnterchangeOefs.AcidCurve(ctxt.h, box, curveProps]}; 

< < Called when an ellipse was encountered while enumerating the contents 
of a graphics container. > > 

Ellipse: GraphicsinterchangeOefs.EIIipseProc = { 

ctxt: GICtxtHandle = clientData; 

GraphjcslnterchangeOefs.AddEllipse[ctxt.h, box, eilipseProps]}; 

< < Called by any proc that's appending a frame to the target doc, 
FilllnFrameCaptions enumerates the contents of each source caption and 
appends everything found to the corresponding new caption. > > 

FilllnFrameCaptions: proc [sourceCaptions, targetCaptions: CaptionsHandle] = { 
crntTC: DoclnterchangeOefs.TextContainer; 
< < The current TextContainer to append stuff to. >> 
procs: DoclnterchangeDefs.EnumProcsRecord <-[ 

fieldProc: Append FieidToCmtTC, newParagraphProc: Append NewParToCrntTC, 

textProc: AppendTextToCrntTCl; 

AppendNewParToCrntTC: OoclnterchangeDefs.NewParagrapliProc s { 

DocjnterchangeOefs. Append NewParagraph [crntTC, paraProps, f ontProps] } ; 

AppendTextToCrntTC: DoclnterchangeDefs. TextProc = { 

DoclnterchangeDefs.AppendText(crntTC, text, textEndContext, fontProps]}; 

AppendFieldToCrntTC: DoclnterchangeDefs.FieldProc = { 
procs: DoclnterchangeDefs. EnumProcsRecord <-[ 

newParagraphProc: AppendNewParToCrntTC, 

textProc: AppendTextToCrntTC); 
newField: DoclnterchangeDefs. Field *- DoclnterchangeDefs.AppendField[ 

crntTC, fieldProps, fontProps]; 
saveTC: DoclnterchangeDefs-TextContainer = crntTC; 
crntTC*- [field (h: newField]]; 

[] 4-DoclnterchangeDefs.Enumerate[[field[h: field]], ©procs]; 

DoclnterchangeDefs. ReleaseField[@newField]; 

crntTC <- saveTC; 

}; - AppendFieldToCrntTC 

- start of FilllnFrameCaptions 

crntTC «- (caption[h: targetCaptions.tc]]; 

[] <- DoclnterchangeDefs. Enumerate[[caption[h: sourceCaptions.tc]], ©procs); 
DoclnterchangeDefs.ReleaseCaption[@targetCaptions.tc]; 

crntTC [caption[h: targetCaptions. be)]; 

[]<- DoclnterchangeDefs. Enumerate[[caption[h: sourceCaptions.be)], ©procs); 
DoclnterchangeDefs.Releas€Caption[@targetCaptions.bc); 

crntTC *- [caption[h: targetCaptions.lc)]; 

[]«- DoclnterchangeDefs. Enunnerate[[caption[h: sourceCaptions.ic]], ©procs); 
DoclnterchangeDefs.ReieaseCaption[@targetCaptions.lcl; 
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J crntTC<--[caption[h: targetCaptions.rc]]; 

[1 <- DoclnterchangeDefs.Enumerate{[captionth: sourceCaptions.rc]], ©procsj; 

DocinterchangeOefs.ReieaseCaption[@targetCaptions.rc]; 

}; - FHIInFrameCaptions 

FiillnText: TabieinterchangeOefs-FiillnTextProc s { 

sourceEntryContent: long pointer to TableinterchangeOefs.EntryContent s 

ciientOata; 
sourcetext: TextlnterchangeOef s. Text; 
targetText: TextlnterchangeOef s.Text = text; 
procs: TextInterchangeOefs,TextEnumProcsRecorcl ( 
newParagraphProc: HitNP, textProc: HItTextl; 

HitNP: DoclnterchangeDefs.NewParagraphProc = { 
TextlnterchangeOefs.AppendNewParagraphToText( 
targetText. paraProps, fontProps]}; 

HItText: DoclnterchangeOefs.TextProc = { 
TextlnterchangeDefs.AppendTextToText[ 
targetText, text, textEndContext, fontProps]}; 

-start of FiillnText 

WITH c: sourceEntryContent f select from 

read = > sourceText<~c.obtainTextProc(c.obtainTextDataI; 

write = > error; 

endcase; 

[]<- TextlnterchangeOef s.EnumerateTextIsourceText,@procsl; 

TextlnterchangeOefs.ReleaseText[@sourceTextI; 

}; -FiillnText 

< < ProQ that's called for each form-field frame in the graphic container. > > 
FormField: GraphicslnterchangeOefs.FormFieldProc = { 
ctxt: GICtxtHandie s ciientOata; 
field: OocinterchangeOefs.Fieid; 
sourceCaptions: CaptionsRec <- [ 

frameProps.captionContent[top], frameProps.captionContent[bottomI, 

frameProps.captionContent(leftl, frameProps.captionContent[right]]; 
newCaptions: CaptionsRec; 
procs: DoclnterchangeOefs.EnumProcsRecord <-[ 

newParagraphProc: AppendNewParToField, 

textProc: AppendTextToField]; 

AppendNewParToFieid: DoctnterchangeOefs.NewParagraphProc s { 
DoclnterchangeOefs.AppendNewParagraph( 
[field[h: field]], paraProps, fontProps]}; 

AppendTextToField: OoclnterchangeOefs-TextProc a { 
DoclnterchangeOefs,AppendText( 

[fieldlh: field]], text, textEndContext, fontProps]}; 

[field, newCaptions.tc, newCaptions. be, newCaptions.ic, newCaptions. re] <— 
GraphicslnterchangeExtra 1 0efs.AddFormFieldX[ 
'""^mgi^ ctxt.h, box, fieldProps, frameProps, 

GraphicslnterchangeExtra lDefs.GetExtraFormFieldProps[content], paraProps, 
fontProps, content # nil, sourceCaptions.tc # nil. sourceCaptions.be # nil. 
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sourceCaptions.lc # nil, sourceCaptions.rc # nil]; 
[] <- DoclnterchangeDefs. Enumerate! 

[fieldth: content]], ©procs ! DoclnterchangeOefs. Error a > {...}]; 
DocI nterchangeOef s. Rel easePi ei d [@f i eld]; 
FilllnFrameCaptions[@sourceCaptions, @newCaptions]; 
}; -FormFiefd 

< < Called when a graphics frame was encountered while enumerating the contents 
of a graphics container. >> 

Frame: GraphicsinterchangeOefs.FrameProc = { 

ctxt: GiCtxtHandle s ctientOata; 

gfh: GraphicsInterchangeDefs. Handle; 

sourceCaptions: CaptionsRec <— [ 

frameProps.captionContent(top], frameProps.captionContent[bottom], 
frameProps.captionContent[left], frameProps.captionContent[right]]; 

newCaptions: CaptionsRec; 

newCtxt: GlCtxt; 

[gfh, newCaptions.tc, newCaptions. be, newCaptions. ic, newCaptions.rc] <- 
GraphicslnterchangeDefs.StartGraphicsFrame( 

ctxt.h, box, frameProps, name, description, nil, sourceCaptions=tc # nil, 
sourceCaptions. be # nil, sourceCaptions.lc # nil, sourceCaptions.rc # nil]; 

newCtxt <~ [gfh. ctxt.sourceOoc, ctxt.targetDoc, false]; 

[] 4- GraphicsInterchangeDefs. Enumerate! 

ctxt. source Doc, graphicsContainer, giEnumProcs, ©newCtxt]; 

Fl i I In Fram eCapti ons[@sou rceCapti ons, @newCa pti ons] ; 

}; -Frame 

FreeCoiumnlnfo: proc [ 

c: LONG pointer TO TablelnterchangeDefs.Columnlnfo, zone: uncounted zone] = { 
FOR i : CARDINAL IN [0..c.length) do 

IF cli].subcolumnlnfo # nil then FreeColumnlnfo[@cn].subcolumnlnfo, zone); 

ENDLOOP; 

zone.FREE[c]; 

}; -FreeCoiumnlnfo 

FreeRowContentlnfo: proc [ 

r: LONG POINTER TO TablelnterchangeDefs-RowContent, zone: uncounted zone] = { 
for i: cardinal IN [0..r.length) DO 
IF r.rowdata[i].subRows # nil then 

for]: cardinal in [0..r.rowdata[i].subRows.iength) oo 

FreeRowContentlnfo[@r.rowdata[i].subRows.rows[]], zone]; 

ENDLOOP; 

endloop; 
zone.FREE[r]; 

}; "FreeRowContentlnfo 

< < Called when an image frame was encountered while enumerating the contents 
of a graphics container > > 

Image: GraphicsInterchangeDefs. ImageProc = { 

ctxt: GiCtxtHandle = clientData; 

sourceCaptions: CaptionsRec <- [ 

frameProps.captionContent(top], frameProps.captionContent[bottom], 
frameProps.captionContent[left], frameProps.captionContent[right]]; 

newCaptions: CaptionsRec; 

[newCaptions.tc, newCaptions.be, newCaptions.lc, newCaptions.rc] <- 
GraphicslnterchangeDefs.Addimage[ 
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ctxt.h, box, imageProps, frameProps, sourceCaptions.tc # nil, 
sourceCaptions.bc # nil, sourceCaptionsJc # nil, sourceCaptjons.rc # nil]; 

FiliinFrameCaptions[@sourceCaptions, ©newCaptions]; 

}; -/mage 

< < Called when a line was encountered while enumerating the contents 

of a graphics container. > > 
Line: GraphicslnterchangeOefs-LineProc s { 

ctxt: GICtxtHandle s ciientData; 

GraphicsinterchangeOefs.AdciLine{ctxt.h, box, iineProps]}; 

Other: GraphicsinterchangeOefs-OtherProc » { 
ctxt: GICtxtHandle a dIentData; 
select objectType from 

barchart, linechart, piechart s > { - for now, turn these into a cluster 

ch: GraphicslnterchangeOefs-Handie s GraphicsinterchangeOefs.StartCIuster[ 
ctxt.h, box]; 

newCtxt: GlCtxt «- [ch, ctxt.sourceOoc, ctxt.targetOoc, false]; 
[] *- GraphicslnterchangeDefs.Enumerate[ 

ctxt.sourceDoc, instance, giEnumProcs, ©newCtxt]; 
GraphicsinterchangeOefs.FinishCluster[ch]; 
); - barchart, linechart, piechart 
piesiice = > { 

piesiiceProps: GraphjcslnterchangeExtra30efs.PieslicePropsRec; 
GraphicslnterchangeExtra30efs.GetPiesiiceProps( 

ctxt.sourceOoc, instance, ©piesiiceProps]; 
GraphicslnterchangeExtra30efs.AddPieslice[ctxt.h, box, ©piesiiceProps]; 
}; -piesiice 
table = >{ 

sourceCaptions, newCaptions: CaptionsRec; 
tableEnumProcs: TablelnterchangeOefs-EnumProcsRec [ 

TableProc, ColumnsProc, RowProcJ; 
tableProps: TablelnterchangeDefs.TablePropsRec; 
extraTableProps: TablelnterchangeExtra 1 pefs.ExtraTablePropsRec; 
h: TablelnterchangeDefs. Handle <- nil; 
frameProps: G ra ph i csl nterchangeDef s. FramePropsRec; 
content: DoclnterchangeOefsJnstance; 

TableProc: TablelnterchangeDefsTableProc = { 
tableProps props t ; 
IF props.spare1 # 0 then { 

tableProps.sparel <- LOOPHOLE(LONG[©extraTableProps]]; 
extraTableProps-deferOnPaginate LOOPHOLE[props.spare1 , 

TablelnterchangeExtra 1 0^fs.ExtraTableProps].deferOnPaginate; 
extraTableProps.spare1 «~0; 

}; 

}; - TableProc 

ColumnsProc: TablelnterchangeOefs-ColumnsProc = { 
newCol urn n Info: TableinterchangeDefs-Columnlnfo 

CopyColumnlnfo(cQlumns, z]; 
h *- TablelnterchangeDefs.StartTable[ 

ctxt.targetDoc, ©tableProps, newColumnlnfo]; 
FreeCol u m n I nf o(@newCol u m ninf o, z] ; 
}; -ColumnsProc 
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RowProc: TableinterchangeDefs.RowProc = { 
newContent: TablelnterchangeOefs-RowContent; 
IF BackgroundProcess.UserAbort[] then RETURN(stop: true]; 
newContent <- Copy RowContent I nfotcontent, z]; 
TablelnterchangeDefs.AppendRow(h, newContent]; 
FreeRowContenti nf o[@newContent» z] ; 
}; -RowProc 

- start of table arm of Other 

content <- GraphicslnterchangeExtra20efs.GetNestedTableProps( 

ctxt.sourceOoc, instance, @frameProps]; 
sourceCaptions <- [ 

frameProps.captionContent[top], frameProps»captionContent(bottom], 

frameProps.captionContent(left], frameProps.captionContent(right]]; 
TablelnterchangeDefs.EnumerateTable(content, ©tableEnumProcs]; 
[newCaptions.tc, newCaptions.be, newCaptionsJc, newCaptions.rc] 

GraphicslnterchangeExtra20efs.AcidTable[ 

h: ctxt.h, box: box, table: TabielnterchangeOefs.FinishTabie[h].table, 
frameProps: ©frameProps, 

wantTopCaptionHandle: frameProps.captionContent(top] # nil, 
wantBottomCaptionHandle: frameProps.captionContent{bottom] # nil, 
wantLeftCaptionHandle: frameProps. captionContent(l eft] # nil, 
wantRightCaptionHandle: franieProps.captionContent[right] # nil]; 
FilllnFrameCaptions[@sourceCaptions, ©newCaptionsj; 
}; "table 
enocase; 
}; -Other 

< < Called when a point was encountered while enumerating the contents 
of a graphics container. > > 

Point: GraphicslnterchangeDefs-PointProc = { 
ctxt: GiCtxtHandle s clientData; 

GraphicslnterchangeDefs.AddPoint[ctxt.h, box, pointProps]}; 

< < Called when a rectangle was encountered while enumerating the contents 
of a graphics container. >> 

Rectangle: GraphicsInterchangeDefs. RectangieProc s { 
ctxt: GiCtxtHandle s cllentOata; 

GraphicslnterchangeDefs.AddRectangle[ctxt.h, box, rectangleProps]}; 

< < Called when a text frame was encountered while enumerating the contents 
of a graphics container. > > 

TextFrame: GraphicslnterchangeDefs-TextFrameProc = { 
ctxt: GiCtxtHandle 3 ciiehtOata; 
sourceCaptions: CaptionsRec ( 

frameProps-captionContentftopl, frameProps.captionContent(bottom], 

frameProps.captionContent[left], frameProps.captionContent[right]]; 
newCaptions: CaptionsRec; 
newContent: Text! nterchangeOefs. Text; 
textProcs: TextinterchangeDefs.TextEnumProcsRecord «- [ 

fieldProc: Append Fi el dToContent, 

newParagraphProc: Append NewParToContent, 

textProc: AppendTextToContent]; 

AppendNewParToContent: DoclnterchangeDefs-NewParagraphProc = { 
TextlnterchangeOefs. Append NewParagraphToText[ 
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newContent, paraProps, fontProps]}; 

AppendTextToContent: DoclnterchangeDefs.TextProc = { 
TextlnterchangeDefs.AppenclTextToText[ 

newContent, text, textEndContext, fontProps]}; 

AppendFieidToContent: DoclnterchangeOefs.FieldProc = { 
procs: DoclnterchangeDefs-EnumProcsRecord <-( 

newParagraphProc: AppendNewParToField, textProc: AppendTextToField]; 
newField: DoclnterchangeDefs.Field TextlnterchangeDefs.AppendFieldToText[ 

newContent, fieldProps, fontProps]; 

AppendNewParToField: OoclnterchangeOefs. NewParagraphProc 3 { 
DoclnterchangeOefs.AppendNewParagraph[ 
[field(h: newFleld]], paraProps, fontProps]}; 

AppendTextToField: OoclnterchangeDefs-TextProc = { 
OoclnterchangeOefs.AppendText[ 

[field[h: newFieid]], text, textEndContext, fontProps]}; 

"Start of AppendFieidToContent 

[] «- DoclnterchangeOefs.Enumerate[[field[h: field]], ©procs]; 
OoclnterchangeOefs. ReleaseField[@newFieid]}; 

[newContent, newCaptions.tc, newCaptions.bc, newCaptions.lc, newCaptions.rc] «- 
GraphicslnterchangeOefs.AddTextFrame[ 

ctxt.h, box, frameProps, textFrameProps, content # nil, sourceCaptions.tc # nil, 
sourceCaptions,bc # nil, sourceCaptionsJc # nil, sourceCaptions.rc # nil]; 

[] <-TextlnterchangeOefs.EnumerateText(content, ©textProcs]; 

TextlnterchangeOefs.ReleaseText(@newContent]; 

FilllnFrameCaptionsI@sourceCaptions, ©newCaptions]; 

}; - TextFrame 

< < Called when a triangle was encountered while enumerating the contents . 

of a graphics container > > 
Triangle: GraphicsinterchangeOefsTriangleProc s { 

ctxt: GICtxtHandle = clientOata; 

GraphicslnterchangeOefs.AddTriangle[ctxt.h, box, triangieProps]}; 
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75.4 Index of Interface Items 

Item 

AddBitmap: proc 
AddCurve: proc 
AddEccentricCurve: proc 
AddEliipse: proc 
AddFormFieid: proc 
AddFormFieldX: proc 
Addlmage: proc 
AddLine: proc 
AddOther: proc 
AddPieslice: proc 
AddPoint: proc 
AddRectangle: proc 
AddTabie: proc 
AddTextFrame: proc 
AddTriangle: proc 

AppendCharToButtonProgram: proc 
AppcindNewParagraphToButtonProgram: 
PROC 

AppendTextToButtonProgram: proc 

BitmapData: type 

BitmapProc: type 

BitmapProps: type 

BitmapPropsRec: type 

BitmapScalingProps: type 

BmOisplay: type 

bmSignature: integer 

Box: type 

Brush: type 

ButtonProc: type 

ButtonProgram: type 

ButtonProgramEnumProcs: type 

ButtonProgramEnumProcsRecord: type 

ButtonProgramObject: type 

ButtonProps: type 

ButtonPropsRec: type 

ClusterProc: type 

CurveProc: type 

CurveProps: type 

CurvePropsRec: type 

Dims: type 

EccentricCurveProps: type 
EccentricCurvePropsRec: type 
EHipseProc: type 
EilipseProps: type 
EllipsePropsRec: type 
Enumerate: proc 
EnumerateButtonProgram: proc 



Page Item Page 

11 EnumProcs: type 17 

6 EnumProcsRecord: TYPE 17 

8 ExtraAnchoredFramePropsEIements: type 6 

9 ExtraAnchoredFramePropsSelections: type 6 

13 FmishButton: PROC 17 

14 FinishCluster: proc 17 

14 FinishGraphics: PROC 17 
9 FinishGraphicsFrame: proc 1 7 

16 FormFieldProc: TYPE 19 

10 FrameProc: TYPE 19 

10 FrameProps: type 4 

10 FramePropsRec: type 4 

15 GetExtraAnchoredFrameProps: PROC 20 

15 Gray: TYPE 9 

11 Handle: TYPE 3 

16 ImageProc: TYPE 19 
ImageProps: TYPE 14 

16 ImagePropsRec: TYPE 14 

16 LineOirection: type 7 

12 LineEnd: type 6 
18 LineEndHead: TYPE 

12 LineProc: TYPE .j 

12 LineProps: type 9 

13 LinePropsRec: type 9 
12 nuilBitmapProps: BitmapPropsRec 21 
12 nullBitmapScalingProps: BitmapScalingProps 22 

3 null ButtonProps: ButtonPropsRec 22 

4 nullCurveProps: CurvePropsRec 22 
18 nullEccentricCurveProps: 

5 EccentricCurvePropsRec 22 
21 nullEllipseProps: EllipsePropsRec 22 
21 nuilFrameProps: FramePropsRec 22 

5 nulllmageProps: ImagePropsRec 22 

5 nullLineProps: LinePropsRec 22 

5 nuilPiesliceProps: PleslicePropsRec 23 
18 nullPointProps: PointPropsRec 23 
18 nullRectangleProps: RectanglePropsRec 23 

6 nuilTextFrameProps: TextFramePropsRec 23 
6 nullTriangleProps: TrianglePropsRec 23 
B Object: type 3 
8 OtherObjectType: TYPE 19 

8 OtherProc: TYPE 19 
18 PiesllceProps: TYPE 10 

9 PleslicePropsRec: type 
9 Place: type 

17 PointFill: TYPE lO 
21 PointProc: type 20 
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Item Page 

PointProps: type 10 

PointPropsRec: type 10 

PointStyie: type 10 

ReadoniyBitmapProps: type 12 

ReadonlyButtonProps: type 5 

ReadoniyCurvaProps: type 6 

ReadonlyEccentricCurveProps: type 8 

Readonly EltipseProps: type 9 

ReadoniyFrameProps: type 4 

ReadonlyimageProps: type 14 

ReadonlyLineProps: type 9 

ReadoniyPiesliceProps: type 10 

ReadonlyPointProps: type 10 

ReadoniyRectangieProps: TYPE 11 

ReadoniyTextFrameProps: TYPE 15 

ReadoniyTriangleProps: TYPE 11 

RectangleProc: type 20 

RectangieProps: TYPE 11 

RectanglePropsRec: TYPE 11 

ReieaseButtonProgram: proc 16 

SetExtraAnchoredFrameProps: proc 6 

Shading: type • 9 

Side: type 4 

StartButton: proc 5 

StartCluster: proc 3 

StartGraphlcs: proc 3 

StartGraphicsFrame: PROC 4 

StyleBrush: type 4 

TextFrameProc: type 20 

TextFrameProps: TYPE 15 

TextFramePropsRec: TYPE 15 

Texture: TYPE 9 

Textures: type 9 

TriangleProc: type 20 

TriangleProps: TYPE 11 

TrianglePropsRec: TYPE 11 
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76.1 Overview 

The IllustratorinterchangeOefs interface provides the mechanisms for the creation and 
enumeration of frames within ViewPoint documents which contain Xerox Pro Illustrator 
graphics. It should be used in conjunction with the OodnterchangeOefs interface. 

A Xerox Pro Illustrator frame is composed of a collection of forms. These forms may be 
simple graphical objects such as lines or curves, or may be more complex, such as clusters 
of forms, or text frames. Forms themselves can have various properties. For example, a line 
has a width and a color, and an area has a texture and a transparency. 

76.1.1 Creating Pro IlIus>trator graphics 

The client creates a Pro Illustrator frame within a document by calling Startlllustrator, 
passing in the required dimensions and frame parameters. This procedure returns a frame 
handle, which is used in subsequent operations on that frame. 

Forms are created within a frame by calling various Create* procedures, such as 
CreateLine. These procedures take only the basic parameters to determine the placement 
of the form within the frame, along with a set of default properties, which determine the 
initial characteristics of the form. Subsequent modification of form properties can be 
accomplished by calling the appropriate Set*Props procedures. 

Once created within the frame, a form must be posted in order for it to be displayed in the 
resulting Pro Illustrator frame. This is accomplished via PostFormAtTop, which causes 
the form to be added on (visiml and structural) top of all forms previously posted in the 
same frame. 

Transformations may be applied to a form after its creation. Procedures such as Rotate 
and Shear perform the corresponding transformations, relative to a pinned point supplied 
by the client. 

Text frames within a Pro Illustrator frame are created by calling CreateText*. The various 
procedures provided allow several different sources to be used for the text itself. 
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When the client has finished creating and manipulating forms, the frame Is completed by 
calling Finishlllustrator. This procedure returns a DodnterchangeDefs.lnstance, which 
should then be passed to OoclnterchangeOefs.AppendAnchoredFrame to enter the Pro 
Illustrator frame into the document. 

76.1.2 Reading Pro Illustrator graphics 

The client can process the contents of an existing Pro Illustrator frame by calling 
Enumerate, passing in the frame handle and a procedure to be called back for each form. 
The frame handle itself can be obtained from an anchored frame by calling 
GetFrameHandle, passing in the DodnterchangeOefsJnstance which corresponds to the 
Pro Illustrator frame. 

Basic information for each type of form can be obtained by calling Get*Data. This includes 
obtaining the location of the end points of a line, or the text content from a text frame. 
Particular groups of properties, not specific to any one type of form, can be obtained by 
calling Get*Props. 

' 76.2 Interface Items 

76.2.1 Creating Pro Illustrator graphics 

76.2.1.1 Creating a frame 

The following procedure creates a new Pro Illustrator frame in which graphics may 
subsequently be created. 

Startlllustrator: procedure [ 

doc: DocinterchangeOefs.Ooc, 
lowerLeft, upperRight: Locn, 
frameUnit: FrameUnit, 
brush: FrameBrush, 

leftMargin, rightMargin, topMargin, bottomMargin: cardinal 4-0] 

RETURNS [ 

ok: BOOLEAN, 

frame: FrameHandie]; 

Startlllustrator creates a new Pro Illustrator frame within doc. The size of the frame, 
exclusive of any frame margins, is determined by iowerLeft and upperRight, measured in 
frameUnit units. These values also determine the coordinate system to be used when forms 
are subsequently added to the frame (including the positive direction of the x and y axes), 
frameUnit defining the unit of measurement for subsequent operations within the frame. 

Locn: type ■ record [x: Scalar, y: Scalar]; 
Scalar: type ■ real; 

FrameUnit: type ■ {mica, millimeter, centimeter, point, point72, pica, inch}; 

Note: In the current implementation, point and point72 are treated as equivalent, and 
correspond to exactly 72 points per inch. 
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The appearance of the frame border is determined by brush. 

FrameBrush: TYPE ■ record [ 
frameBorderWidth: Pixels, 
frameBorderStyie: FrameBorderStyie]; 

Pixels: type ■ cardinal; 

FrameBorderStyie: TYPE ■ machine dependent { 

invisible(0), soiid(1 ), dashed(2), datted(3). doubie(4). broi(en(5}, (1 5)}; 

The size of the margin on each side of the frame is determined by leftMargin, rightlVlargin, 
toplS^argin, and bottomiy/largin, measured in micas. 

The FrameHandle returned by Startlllustrator is passed to the various procedures used to 
add forms to the newly created frame. 

FramelHandle: TYPE [2]; 

A frame may also be created by copying an existing Pro Illustrator frame. 

CopyFrame: procedure [ 
frame: FraifneHandle, 
doc: OoclnterchangeDefs.Ooc, 
brush: FrameBrush, 

leftiy^argin, rightMargin, topiy/largin, bottomMargin: CARDINAL 0] 

RETURNS [ 

ok: BOOLEAN, 

copy: FrameHandle]; 

frame is the frame to be copied. The document into which the frame is to be copied is 
identified by doc, and may be the same as, or different from, the document containing 
frame. As with Startlllustrator, brush determines the appearance of the frame border, and 
leftMargin, rightMargin, topMargin, and bottomMargin specify the frame margins. 

76.2.1.2 Creating forms 

After creating the frame by calling Startlllustrator, the client will typically add forms to it 
by calling various Create* procedures, described below. To each of these procedures the 
client passes the FrameHandle returned by Startlllustrator and the default properties to be 
used, as well as form-dependent parameters. (See Section 76.2.3.3 for details of default 
properties.) Each returns a FormHandle, used in subsequent operations on the form. 

FormHandle: type [2]; 

niiFormHandle: FormHandle ■ loophole[lon€[nil]]; 

The procedures used to create forms are divided into several groups: basic forms, clusters, 
trajectories and shapes, and text frames. These are described in separate sections below, 
followed by a section on copying an existing form. 
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Basic forms 

CreatePoint: procedure [ 
frame: FrameHandie, 
locn: Locrir 

defaultProps: DefauitProps] 
RETURNS [FormHandle]; 

CreatePoint creates a point form at the location specified by locn. 

CreateLine: procedure [ 
frame: FrameHandle, 
locnA, tocnB: Locn, 
defaultProps: DefaultProps] 
returns [FormHandle]; 

CreateLine creates a line form with start and end points specified by locnA and locnB. 

CreateRectangle: procedure [ 
frame: FrameHandle, 
pointA, poinK: Locn, 
defaultProps: DefauitProps] 
RETURNS [FormHandle]; 

CreateRectangle creates a rectangle form whose size and placement are determined by 
specif3ring two diagonally opposed vertices of the rectangle, pointA and polntC. The order 
in which these vertices are specified is not significant. 

CreateParailelogram: procedure [ 
frame: FrameHandle, 
pointA, points, pointC: Locn, 
defaultProps: DefaultProps] 
RETURNS [FormHandle]; 

CreateParailelogram creates a parallelogram form whose size, shape and placement are 
determined by pointA, pointB and pointC, these being any three consecutive vertices of the 
parallelogram. 

CreateEllipse: procedure [ 
frame: FrameHandle, 
pointA, pointB, pointC: Locn, 
defaultProps: DefaultProps] 
RETURNS [FormHandle]; 

CreateEllipse creates an ellipse form whose size, shape and placement are determined by 
pointA, pointB and pointC, these being any three consecutive vertices of the bounding 
parallelogram for the ellipse. 
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Clusters 

A cluster is a form which is itself a grouping of forms, created by joining the forms of which 
it is to be composed. The resultant cluster can then be manipulated as a single entity. 
Note that clusters may themselves be part of another cluster. 

Join: PROCEDURE [enumerateProc: EnumerateFormsProc, count: cardinal 4-0] 
RETURNS [FormHandle]; 

EnumerateFormsProc: type ■ procedure [formCailBack: AcceptFormProc]; 
AcceptFormProc: TYPE ■ procedure [form: FormHandle]; 

The enumerateProc, supplied to Join by the client, is called back to obtain the forms which 
are to comprise the cluster. For each of these forms, the client should call the 
formCallBack, as passed into the enumerateProc, to add it to the cluster. 

count is the number of forms which will comprise the cluster. If count is zero, the 
enumerateProc will be called once to count the forms, and then called again to build the 
cluster itself. 

Trajectories and shapes 

A shape is a form which corresponds to a (possibly filled) geometric'shape, and is composed 
of a number of trajectories. Each trajectory is composed of a sequence of edges, and may be 
either open or closed. A closed trajectory is analogous to a polygon, and an open trajectory 
'"■"^ to a polyline. 

A shape is created by calling CreateShape. 

CreateShape: procedure [ 
frame: FrameHandle, 
defauitProps: DefaultProps] 
RETURNS [FormHandle]; 

frame is the frame within which the shape is to be created, and defauitProps contains the 
default properties for the form. 

Trajectories are added to a shape by calling AddTrajectory. 
AddTrajectory: procedure [trajectory* shape: FormHandle]; 

A trajectory is itself created by calling CreateTrajectory. 

CreateTrajectory: procedure [ 
frame: FrameHandle, 
edges: cardinal, 
closed: boolean true, 
boundary Type: Boundary Type <- Including, 
defauitProps: DefauitProps] 
'^"^m^ RETURNS [currentForm: FormHandle]; 
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frame is the frame within which the trajectory is to be created, edges specifies the number 
of edges in the trajectory, and closed specifies whether the trajectory is closed or open. 

Each trajectory has a boundary type which may be either including or excluding. A 
boundary type of including will cause a shade or texture fill to fill inside the trajectory, 
whilst one o£ excluding will cause the fill to fill outside. This enables objects with ''holes" to 
be constructed. Figure 76.1 illustrates a shape composed of a rectangular trajectory with 




Figure 76. 1 A shape with a "hole" 



boundary type including and a triangular trajectory with boundary t3rpe excluding, and 
filled with 50% gray. 

BoundaryType: type ■ {including, excluding}; 
Edges are added to the trajectory by calling AddEdge. 
AddEdge: procedure [trajectory: FormHandle, edge: Edge]; 

This causes edge to be added to trajectory. The edges of a trajectory may be lines, conies, 
bezier curves or arcs. 

EdgeType: type ■ {lineTo. conicTo, bezierTo, arcTo}; 

Edge: TYPE « lonq pointer to readonly EdgeObject; 
EdgeObject: type ■ record [ 

smoothJoint: BOOLEAN 4-false, 

data: select type: EdgeType from 
lineTo ■ > [vertex: Locn]« 

conicTo ■ > [apex: Locn, eccentricity: Scalar, vertex: Locn], 
bezierTo ■ > [apexA, apexB, vertex: Locn], 
arcTo ■ > [direction: DirectionType^- clockwise, 

pointA, points, pointC vertex: Locn], 
endcase]; 

Since each edge of a trajectory starts at the end point (the vertex) of the previous edge, no 
starting point for an edge needs to be specified. For a closed trajectory, the first edge starts 
at the vertex of the last edge. For an open trajectory, the first edge defines the starting 
point of the trajectory (via its vertex), but is otherwise ignored. 
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A conic is specified by its apex and eccentricity, as illustrated in Figure 76.2. For 




Figure 76.2 Specification of a conic 

convenience, the following constant defines the eccentricity of a circle. 
eccCircle: real • .414213; - Sqrt [2.0] - 1.0 

A bezier curve is specified by two bend points, apexA and apexB, as illustrated in Figure 
76.3. 




: y 

m 



Figure 76.3 Specification of a bezier curve 

An arc, which may be either circular or elliptical, is speciSed by its direction, which may be 
either clockwise or counter-clockwise, and three points on its bounding parallelogram, as 
illustrated in Figure 76.4. 

DirectionType: type ■ {clockwise, counterclockwise}; 

Note: In the current version, a trajectory can appear only inside a shape, only one 
trajectory per shape is permitted, and boundary Type is always taken as including. 

Text frames 

Text frames within a Pro Illustrator frame may be created in one of four different ways, 
depending upon the source of the text content itself. In each case, the client passes in 
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Figure 76.4 Specification of an arc 



frame, which is the Pro Illustrator frame within which the text frame is to be created, 
pointA and pointC, which are two diagonally opposed vertices of the text frame, and 
defaultProps, which are the default properties to be used in creating the text frame. (See 
Section 76.2.3.3 for details of default properties.) The text frame form is returned in 
FormHandle. 

Although the size and placement of a text frame is initially specified via pointA and 
polntC, this may be altered during creation if the frame has any varying sides , as 
detiermined from defauitProps. Since changing the frame to have fixed sides after it is 
created will not restore the frame's original size, the correct properties should be set within 
defauitProps before calling CreateText*. (See Property Groups in Section 76.2.3.2 for 
details of text properties.) 

CreateText: procedure [ 
frame: FrameHandle, 
pointA, pointC: Locn, 
defauitProps: DefauitProps, 
string: XString.Reader«-Niu 

paraProps: OodnterchangePropsOefs.ReadoniyParaProps «-niu 
fontProps: DoctnterchangePropsOefs.ReadoniyFontProps 4- nil] 
RETURNS [FormHandle]; 

CreateText creates a text frame containing the text supplied in string, with paragraph and 
font properties determined by paraProps and fontProps respectively. 

CreateTextFromTextType: procedure [ 
frame: FrameHandle, 
pointA, pointC: Locn, 
defauitProps: DefauitProps, 
string: XString.Reader 4-nil, 
textContent: TextlnterchangeDefs.Text «-nil] 
RETURNS [FormHandle]; 

CreateTextFromTextType creates a text frame containing the text supplied in textContent 
preceded by that supplied in string, if any. This allows, for example, the copying of text 
from another text frame. 
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CreateTextFromFieid: PROCEDURE [ 
frame: FrameHandle, 
pointA, pointC: Locn, 
defauitProps: DefaultProps, 
string: XString.Reader ^-niu 
fieidContent: OoclnterchangeDefs.Fieid 
paraProps: DodnterchangePropsOefs.ReadoniyParaProps 4- nil, 
fontProps: OacinterchangePropsOefs.ReadonlyFontProps 4- nil] 
RETURNS [FormHandie]; 

CreateTextFromFieid creates a text frame containing tiie text supplied in fieidContent, 

preceded by that supplied in string, if any, with paragraph and font properties determined 
by paraProps and fontProps respectively. This allows the cop3ring of text from a field 
within a ViewPoixit document into a text frame within a Pro Illustrator frame. 

CreateTextFromCaption: procedure [ 
frame: FrameHandle, 
pointA, pointC: Locn, 
defauitProps: DefauitProps, 
string: XString.Reader 4~niu 
captionContent: DodnterchangeOefs.Caption 4-nil, 
paraProps: DoclnterchangePropsDefs.ReadoniyParaProps <-niu 
fontProps: OoclnterchangePropsOefs.ReadonlyFontProps 4-nil] 
RETURNS [FormHandie]; 

CreateTextFromCaption creates a text frame containing the text supplied in 
captionContent, preceded by that supplied in string, if any, with paragraph and font 
properties determined by paraProps and fontProps respectively. This allows the copying of 
text from a frame caption into a text frame within a Pro Illustrator frame. 

Copying a form 

A form may also be created by copying an existing form. 

Copy Form: procedure [ 
form: FormHandie, 

toFrame: FrameHandle «- nilFrameHandle] 
RETURNS [FormHandie] ; 

nilFrameHandle: FrameHandle ■ L00PH0LE[L0NG[NiL]]; 

CopyForm creates and returns a copy of form within frame toFrame. If toFrame is 
nilFrameHandle, the form will be copied within the same frame 

76.2.1.3 Posting forms 

For a form to be visible within a displayed or printed Pro Illustrator frame, it must be 
posted after its creation. However, forms within a cluster should not themselves be posted, 
since posting the cluster achieves the correct result. 



76-9 



76 lUustratorlnterchangeDefs 



PostFormAtTop: procedure [form: FormHandle]; 

PostFormAtTop causes form to be imaged on top of all forms previously created within this 
frame. 

A form may be unposted, or removed from the list of forms to be imaged within the frame, 
by calling UnPostForm. 

UnPostForm: procedure [form: FormHandle]; 

76.2.1.4 Form transformations 

After its creation, a variety of transformations may be applied to a form. Each of the 
following procedures performs a transformation on the form passed in, returning a boolean 
value indicating whether the form was actually changed or whether in fact the identity 
transformation took place. 

Magnify: procedure [ 
form: FormHandle, 
pin: Locn, 
scale: Scalar] 

returns (changed: boolean]; 

Magnify causes form to be magnified by a factor of scale, centered around the pinned point, 
pin. Everything, including line widths, line endings and point widths, is magnified in 
proportion. 



Note: While text frames can be magnified (subject to automatic constraints if they have 
varying edges), the text inside them is not. Also, the length of segments in dashed lines is 
not affected by magnification. 

Mirror: procedure [ 
form: FormHandle, 
pin: Locn, 
axis: Axis] 

RETURNS [changed: boolean]; 
Axis: TYPE ■ {x, y, origin, yEqualsX, yEqualsMinusX}; 

Mirror causes form to be reflected in the axis specified by axis and passing through the 
pinned point, pin. If axis is origin, then the reflection occurs through the pinned point, pin. 

Note: Mirroring in the yEqualsX and yEqualsMinusX axes are currently not supported. 

Rotate: procedure [ 
form: FormHandle, 
pin: Locn, 
sin, cos: Scalar] 
returns [changed : boolean] ; 
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Rotate causes form to be rotated by 9 degrees around the pinned point, pin, where sin and 
cos are the sine and cosine, respectively, of 8. 

Note: Embedded frames (currently only text frames) are not rotated, but instead keep 
their orientation and are moved along the path of the rotation. 

Scale: procedure [ 

form: Form Handle, 
pin: Locn, 

xScaleFactor: Scalar, 
yScaieFactor: Scalar] 
RETURNS [changed: boolean]; 

Scale causes form to be scaled by a factor of xScaleFactor in the X axis, and yScaieFactor in 
the Y axis, centered around the pinned point, pin. Line widths and line endings are not 
affected. 

Note: While text frames can be scaled (subject to automatic constraints if they have 
varying edges), the text inside them is not. 

Shear: procedure [ 
form: FormHandle, 
pin: Locn, 

shearFactor: Scalar, 
scaleFactor: Scalar, 
axis: Axis] 

returns [changed: boolean]; 

Shear causes form to be sheared by a factor of shearFactor in the axis axis, and scaled by a 
factor of scaleFactor in the orthogonal axis, centered around the pinned point, pi n. 

Note: Shearing in the yEqualsX and yEqualsMlnusX axes are currently not supported. 
Embedded frames (currently only text frames) are not sheared, but instead keep their 
orientation and are moved along the path of the shear. 

Translate: procedure [ 
form: FormHandle, 
xOffset: Scalar, 
yOffset: Scalar, 
guidePtLocn: Locn origin, 
mode: TranslateMode 4- relative] 
RETURNS [changed: boolean]; 

TranslateMode: type ■ {absolute, relative}; 

If mode is absolute. Translate causes form to be translated by an amount such as to 
position the guide point, guidePtLocn, at the point (xOffset, yOffset). If mode is relative, 
form is translated by xOffset in the X axis and yOffset in the Y axis. 
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76.2.1.5 Finish routines jii^ 

When all the desired forms have been added to the frame, the client should call 
Finishlllustrator, passing in the FrameHandle originally returned by Startlllustrator. 

Finishlilustrator: procedure [frame: FrameHandIa] 
RETURNS [illustrator: OodnterchangeOefs.lnstance]; 

The client will typically pass illustrator to OodnterchangeOefs.AppendAnchoredFrame to 
insert the frame into a document. 

76.2.2 Reading graphics 

This section details the procedures used to perform basic enumeration of the forms within a 
Pro Illustrator frame. Interrogation of the properties of forms is achieved througii use of 
the procedures described in the next section. 

The client enumerates the forms within a Pro Illustrator frame by calling Enumerate. 

Enumerate: procedure [frame: FrameHandle, proc: FormProc] 
RETURNS [stopped: boolean 4- false]; 

FormProc: type ■ procedure [form: FormHandle] returns [stop: boolean false]; 

frame is the handle of the Pro Illustrator frame to be enumerated. The client-supplied proc j^it^ 
is called back for each form in the frame, in bottom to top order. If proc returns stop « trui 
at any time, the enumeration is terminated, and Enumerate returns to the client with 
stopped ■ true. 

In order to enumerate the forms within a cluster, or trajectories within a shape, the client 
should call the following procedure. 

EnumerateSubForms: procedure [form: FormHandle, proc: AcceptFormProc]; 

The client-supplied proc is called back for each form in the cluster, or trajectory within the 
shape. 

In order to enumerate the edges within a trajectory, the client should call the following 
procedure. 

EnumerateEdges: procedure [form: FormHandle, proc: EdgeProc] 
RETURNS [stopped: BOOLEAN 4- false]; 

EdgeProc: TYPE ■ procedure [edge: Edge] returns [stop: boolean «- false]; 

The client-supplied proc is called back for each edge in the trajectory. If proc returns stop 
■ true at any time, the enumeration is terminated, and EnumerateEdges returns to the 
client with stopped ■ true. 
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76.2.3 Properties 

Previous sections of this chapter have dealt with the creation and enumeration of frames 
and forms in their basic state. This section details the properties applicable to frames and 
to each type of form, and describes the procedures available to set and interrogate those 
properties. 

76.2.3.1 Frame properties 

The following procedures allow the client to get and set various properties of a Pro 
Illustrator frame. The Get* procedures take a FrameHandie as a parameter, and return 
the appropriate type of information as their result. The Set* procedures take a 
FrameHandie and the appropriate information as parameters. 

GetFrameHandle: procedure [anchoredFrame: DodnterchangeOefsJnstance] 
RETURNS [FrameHandie]; 

GetFrameHandle returns the handle for an anchored Pro Illustrator frame within a 
document. anchoredFrame will typically have been passed to the client as. a result of a call 
to DoclnterchangeOefs.Enumerate. 

GetBoundary: procedure [frame: FrameHandie] returns [lowerLeft, upperRight: Locn]; 

SetBoundary: procedure [frame: FrameHandie, lowerLeft, upperRight: Locn]; 

GetBoundary and SetBoundary allow the client to get and set, respectively, the bounding 
box for a frame. The values lowerLeft and upperRight define the size of the frame and the 
coordinate System to be used within it. 

GetFrameUnit: procedure [frame: FrameHandie] returns [FrameUnit]; 

SetFrameUnit: procedure [frame: FrameHandie, framelinit: FrameUnit]; 

GetFrameUnit and SetFrameUnit allow the client to get and set, respectively, the unit of 
measurement to be used in subsequent operations withiii the frame. 

GetGridding: procedure [frame: FrameHandie] returns [Griddinglnfo]; 

SetGridding: procedure [frame: FrameHandie, gridding: Griddinglnfo]; 

GetGridding and SetGridding allow the client to get and set, respectively, the parameters 
affecting the use of a grid within the frame. 

Griddinglnfo: type ■ long pointer to readonly GriddingObject; 
GriddingObject: TYPE ■ record [ 

xGrid, yGrid: Scalar ^ 0.0, 

rGrid, thetaGrid: Scalar 4- 0.0, 

cartesianGridOrigin: Locn <- origin, 

polarGridOrigin: Locn <- origin, 

thetaGridOffset: Scalar <- 0.0, 

display Grid: boolean <- false, 

gridStyle: GridStyle ^ none. 
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gridType: GridType <— none, 
x<aridOn, yGridOn: boolean <~pai.se, 
rGridOn, thetaGridOn: boolean false]; 

GridStyle: TYPE ■ {tic, dot. none}; 
GridType: type ■ {linear, angular, none}; 

origin: Locn ■ [0.0,0.0]; 

Botii cartesian and polar grids are provided for within a Pro Illustrator frame, that which 
is active (if any) being indicated by gridType. Whether or not the grid is visible to the user 
is determined by displayGrid, and the style of grid points, when visible, is specified by 
gridStyie. 

Note: gridStyle ■ tic is not supported in the current version. 

For a cartesian grid, X and Y grid control is independently specifiable. Whether or not X or 
Y positioning is to be constrained by the grid is specified by xGridOn and yGridOn 
respectively. The grid spacing is specified by xGrid and yGrid, measured from the grid 
origin, cartesianGridOrigin. 

For a polar grid, r and 8 grid control is independently specifiable. Whether or not r or 0 
positioning is to be constrained by the grid is specified by rGridOn and thetaGridOn 
respectively. The grid spacing is specified by rGrid measured from the grid origin, 
polarGridOrigin, and by thetaGrid measured in degrees around the grid origin, starting at 
thetaGridOff set degrees. 

GetTopForm: procedure (frame: FrameHandle] returns [FormHandie]; 

GetBottomForm: procedure [frame: FrameHandle] returns [FormHandie]; 

GetTopForm and GetBottomForm return the handle of the top and bottom form, 
respectively, within the imaging order of the frame whose handle is passed in. 

76.2.3.2 Form properties 

The following procedures allow the client to get and set various properties of a form. These 
procedures are divided into three groups, reflecting their applicability to all types of forms, 
to specific types of forms, or to specific types of properties. A further section is devoted to 
the subject of line dash styles. 

Generic form properties 

These procedures return to the client information about the form in its context within the 
frame. They are applicable to all type of forms. 

GetParentFrame: procedure [form: FormHandie] returns [FrameHandle]; 

GetParentFrame returns the handle of the Pro Illustrator frame within which the form 
exists. 
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GetFormType: procedure [form: FormHandle] returns [FormType]; 
FormType: type ■ { 

point, line, rectangle, parallelogram, eilipse,trajectory, shape, cluster, text, frame}; 

GetFormType returns the type of the form whose handle is passed in. 

GetFormAbove: procedure [form: FormHandle, circular: boolean <- false] 
returns [FormHandle]; 

GetFormBelow: procedure [form: FormHandle, circular: boolean <- false] 
returns [FormHandle]; 

GetFormAbove and GetFormBelow return the form above and below, respectively, the 
form whose handle is passed in, within the imaging order of the frame. Ordinarily, 
GetFormAbove returns nil if form is the top form,and GetFormBelow returns nil if form is 
the bottom form. However, if circular = true, both functions "wrap around", that is, 
GetFormAbove of the top form returns the bottom form, and GetFormBelow of the bottom 
form returns the top form. 

Specific form properties 

Each of these procedures returns to the client the pertinent information for the particular 
type of form whose handle is passed in. 

GetPointData: procedure [form: FormHandle] returns [point: Locn]; 

GetPointOata returns the location of the point passed in. 

GetLineOata: procedure [form: FormHandle] returns [pointA, pointB: Locn]; 

GetLineOata returns the start and end points of the line passed in. 

GetParallelogramOata: procedure [form: FormHandle] 

returns [isRectangle: boolean, pointA, pointB, pointC: Locn]; 

GetParallelogramOata returns three consecutive vertices of the parallelogram passed in, 
and indicates whether or not the parallelogram is in fact a rectangle. 

GetElilpseOata: procedure [form: FormHandle] returns [pointA, pointB, pointC: Locn]; 

GetEllipseData returns three consecutive vertices of the bounding parallelogram for the 
ellipse passed in. 

GetClusterOata: procedure [form: FormHandle] returns [count: cardinal]; 

GetClusterData returns, for the shape passed in, a count of the number of forms of which it 
is composed. 

GetShapeData: procedure [form: FormHandle] returns [count: cardinal]; 
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GetShapeOata returns, for the shape passed in, a count of the number of trajectories of 
which it is composed. 

GetTrajectoryOata: procedure [form: FormHandle] 

RETURNS (count: CARDINAL, ciosed: BOOLEAN, boundaryType: BoundaryType]; 

GetTrajectoryOata returns the number of edges in the trajectory, an indication of whether 
it is closed or not, and the boundary type, for the trajectory passed in. 

GetTextData: procedure [doc: DoclnterchangeOefs.Doc,form: FormHandle] 
RETURNS [text: TextlnterchangeOefs.Text]; 

GetTextOata returns, for the text frame passed in, the text content for that frame. 
Property groups 

There are several groups of properties which are not directly connected to a particular type 
of form, but which may in fact be associated with several different types of forms. For each 
such group, three procedures are provided, viz Has*Props, Get*Props and Set*Props. For a 
given form, these procedures allow the client to determine whether the form possesses the 
properties, to get the properties, and to set them, respectively. 

Has*Props procedures return true if the form has that particular type of property - that is, 
if the property is appropriate for the form - and false otherwise. For example, line 
properties are appropriate for lines, but area properties are not. The client should call the 
appropriate Has^Props procedure to determine the appropriateness of properties before 
calling Get^Props or Set*Props. 

Get*Props procedures return the form property if that property -is appropriate and 
consistent. For example, lines have line properties, but a cluster of lines might have 
inconsistent (i.e. different) line properties. If the property is inappropriate, nil is returned; 
if it is inconsistent or does not exist, the value undef ined*Props is returned. 

Note that both line end properties and area properties are appropriate for shape forms, but 
that line end properties are used only on open trajectories, and area properties only on 
closed trsy'ectories. 

Area properties are normally applicable to rectangles, parallelograms, ellipses, closed 
trajectories and text frames, and may be applicable to clusters. 

HasAreaProps: procedure [form: FormHandle] returns [boolean]; 

GetAreaProps: procedure [form: FormHandle] returns [AreaPropsObject]; 

SetAreaProps: procedure [form: FormHandle, areaProps: AreaProps]; 

AreaProps: type « long pointer to AreaPropsObject; 
AreaPropsObject: type ■ record [ 

arealexture: AreaTexture, 

areaColor: Color, 

transparent: Boolean]; 



76-16 



Viewpoint Programmer's Manual 



Boolean: TYPE ■ {true, false, undefined}; 

An area has a texture and a color, and may be either transparent or opaque. A v£u:iety of 
basic textures are provided, and these may be used singly or in combination to achieve the 
desired effect. 

AreaTexture: type ■ record [ 

- line - 

lineVert, lineHoriz, lineNW, lineNE, 

- dash - 

dashNW, dashNE, bricic, crossweave, 

- other - 

stipple, whiteArc, wave, squareOot: Boolean]; 

As a convenience, noAreaTexture allows the client to specify the absence of any texture 
within an area. 

noAreaTexture: AreaTexture • [ 

false, false, false, false, false, false, false, false, false, false, false, false]; 

Color, as a shade of gray. Is specified as a value in the range 0 to 1, where 0 and 1 represent 
white and black respectively. 

Color: TYPE ■ Scalar; 

The following definition represents no specification of area properties. Note that this is 
different from specification of no area properties. 

undefinedAreaProps: AreaPropsObject » [ 

undefinedAreaTexture, undefinedScalar, undefined]; 

undefinedAreaTexture: AreaTexture ■ [ 

undefined, undefined, undefined, undefined, undefined, undefined, 
undefined, undefined, undefined, undefined, undefined, undefined]; 

undefinedScalar: Scalar ■ Real.LargestNumber; 

Graphic properties are applicable to all form types. 

HasGraphicProps: procedure [form: FormHandle] returns [boolean]; 

GetGraphicProps: procedure [form: FormHandle] returns [GraphicPropsObject]; 

SetGraphicProps: procedure [form: FormHandle, graphicProps: GraphicProps]; 

GraphicProps: type ■ long pointer to GraphicPropsObject; 
GraphicPropsObject: type ■ record [ 

fixedAngle: Boolean, 

fixedShape: Boolean, 

printable: Boolean]; 
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printable determines whether or not the form should be printed in addition to being 
displayed on the screen. 

Note; f ixedAngle and f ixedShape are not implemented in the current release. 

The following definition represents no specification of graphic properties. 

undefinedGraphicProps: GraphicPropsObject ■ [undefinedr undefined, undefined]; 

Point properties are applicable to points, and may be applicable to clusters. 

HasPolntProps: procedure [form: FormHandie] returns [boolean]; 

GetPolntProps: procedure [form: FormHandie] returns [PolntPropsObject]; 

SetPointProps: procedure [form: FormHandie, pointProps: PointProps]; 

PointProps: TYPE • long pointer TO PolntPropsObject; 
PolntPropsObject: TYPE ■ record [ 

pointMaricer: PointMarlcer, 

polntWidth: Scalar, 

poinKolor: Color]; 

A point has a marker type, a width aitd a color. A variety of markers are provided. Width, 
which is the effective diameter of the point, is specified in the current frame units. As for 
areas, color is specified as a value in the range 0 to 1, where 0 and 1 represent white and 
black respectively. 

PointMarker: type ■ { 

- solid - 

solidSquare, soiidCircle, solidOiamond, solidUpTriangle, 
solidDownTriangle, solidRlghtTriangle, solidLeftTriangle, 
-open- 

openSquare, openCrcle, openOiamond, openUpTriangie, 
openOownTrlangie, openRightTriangle, openLeftTriangle, 
-nDot- 

squareNDot, circleNDot, diamondNDot, 

- misc - 

solidDiscRising, solidOiscSetting, solidStar, 
X, plus, outlineOiscRising, outlineOiscSetting, 
openStar, starburst, check, 
undefined}; 

The following definition represents no specification of point properties. 

undefinedPointProps: PolntPropsObject ■ [ 

undefined, undefinedScalar, undefinedScalar]; 

Line properties are applicable to lines, rectangles, parallelograms, ellipses, trajectories 
and text frames, and may be applicable to clusters. 

HasLlneProps: procedure [form: FormHandie] returns [boolean]; 
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GetLineProps: procedure [form: FormHandie] returns [LinePropsObject]; 

SetLineProps: procedure [form: FormHandie, lineProps: LineProps]; 

LineProps: type * long pointer to LinePropsObject; 
LinePropsObject: type ■ record [ 

lineTexture: LineTexture, 

dashStyle: OashStyle, 

lineWidth: Scalar, 

lineColor: Color]; 

A line has a texture, a width and a color. If the line texture is dashed, the line has a dash 
style. Dash styles are described in the next section. 

LineTexture: type ■ {solid, dashed, none, undefined}; 

The following definition represents no specification of line properties. 

undefinedLineProps: LinePropsObject « [ 

undefined, NIL, undefinedScalar, undefinedScalar]; 

Line end properties are applicable to lines and trajectories, and may be applicable to 
clusters. 

HasLineEndProps: procedure [form : FormHandie] returns [boolean]; 

"^^mt^ GetLineEndProps: procedure [form: FormHandie] returns [LineEndPropsObject]; 

SetLineEndProps: procedure [form: FormHandie, lineEndProps: LineEndProps]; 

LineEndProps: type ■ long pointer to LineEndPropsObject; 
LineEndPropsObject: type ■ record [ 

endingA: LineEnding, 

endSizeA: Scalar. 

fixedOrVaryingA: FixedOrVarying, 
endingB: LineEnding, 
endSizeB: Scalar, 

fixedOrVaryingB: FixedOrVarying]; 

For each end of the line, the LineEndPropsObject specifies the type and size of the line 
ending, and whether it is fixed or variable. The size of a fixed line ending is specified by 
size, and remains unchanged when the line width itself is scaled, size represents the line 
width for which the arrowhead is proportionately correct. For a variable line ending, size 
is ignored, and the actual size is determined from the line width. Variable line endings are 
scaled along mth the line itself. 

LineEnding: type ■ { 

- basic - 

extended, flush, rounded, 

- solid arrows - 

arrowSoiidMiddleFlatSacIc, arrowSoiidShortFlatSack, 
arrowSolidEquilFlatBack, arrowSolidSkinnyFlatBacic, 
arrowSolidSmallVBack.arroyvSolidLargeVBack, 
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» outline arrows -- 

arrowOutimeMiddleFtatBack,arrowOutlineShortFlatBack, 
arrowOutlineEquilFlatBack, arrowOutlineSkinnyFiatBack, 
arrowOutlineSmaiiVBack. arrowOutlineLargeVBack, 

- V arrows - 

arrowVLong, arrowVFIatTop, 

-» misc - 

solidCrdet outlineCirde, break, slash, 

- double arrows 

doubleMlddieFiatBack, doubleEquilFlatBack, doubleSmallVBack, 
undefined}; 

FixedOrVarying: type ■ {fixed, varying, undefined}; 

The following definition represents no specification of line end properties. 

undefinedLineEndProps: UneEndPropsObject « [ 

undefined, undefinedScaiar, undefined, undefined, undefinedScaiar, undefined]; 

Text properties are applicable to text frames, and may be applicable to clusters. 

HasTextProps: procedure [form: FormHandle] returns [boolean]; 

GetTextProps: procedure [form: FormHandle] returns [TextPropsObject]; 

SetTextProps: procedure [form: FormHandle, textProps: TextProps]; 

TextProps: type « long pointer to TextPropsObject; 
TextPropsObject: type « record [ 

leftEdge, rIghtEdge, topEdge, bottomEdge: FixedOrVarying, 

ctrlPtPlace: CtrlPtPlace, 

leftMargin, rightMargin,topMargin, bottomMargin: Scalar]; 

Each edge of a text frame may be either fixed or varying. When an edge is specified as 
varying, its position is determined by the textual content of the frame, whereas the 
position of a fixed edge will not be altered in this way. The margin for each edge is 
independently specificable, and the positioning of control points for the text frame is 
determined by ctrlPtPlace. 

CtrlPtPlace: type ■ {baseline, center, baselineAndCenter, undefined}; 

When CtrlPtPlace is center, control points for the text frame are positioned the same as for a 
rectangle. When ctrlPtPlace is baseline, the control points In the middle of the left and right 
sides and in the center of the frame are positioned along the baseline of the first line of text. 

Note: baselineAndCenter is not supported in the current version. 

The following definition represents no specification of text properties. 

undefinedTextProps: TextPropsObject ■ [ 

undefined, undefined, undefined, undefined, undefined, 
undefinedScaiar, undefinedScaiar, undefinedScaiar, undefinedScaiar]; 
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Dash styles 

Pro Illustrator allows the creation and use of arbitrary dash styles for lines and 
trajectories. Due to this arbitrary nature, a special mechanism exists for their 
manipulation, the details of which are described in this section. 

A dash pattern can be considered as a sequence of pairs of arbitrary length, each pair 
comprising a dash and a gap. Hence a regular dashed line would consist of a single pair, 
with the dash and ga.p of equal length, and a dash-dot line would consist of two pairs, the 
two dash lengths being different. 

^ The client creates a new dash style by calling CreateOashStyle. 

CreateDashStyie: procedure [ 
zone: uncounted zone, 
fit: DashFit. 

enumerateProc: EnumeratePatternProc] 
RETURNS [DashStyle]; 

DashStyle: TYPE a long pointer; 

The storage for the new dash style will be allocated from zone, fit determines the 
behaviour of the dash pattern within a line. 

DashFit: type ■ {fromOneEnd, centered, stretchToFtt, stretciiToVertices}; 

fromOneEnd causes the dash pattern to be applied, repeatedly if necessary, without 
stretching, and starting with the first dash at the first vertex of the trajectory, centered 
causes the dash pattern to be applied without stretching and starting at the center of the 
trajectory. stretchToFit causes the dash pattern to be stretched as necessary so that each 
end of the trajectory has a full dash. stretchToVertices causes the dash pattern to be 
stretched as necessary, separately for each segment, so that each vertex of the trajectory 
has a full dash. 

Note: Only fit — fromOneEnd is currently implemented. 

The client-supplied enumerateProc is called back to obtain the pairs comprising the dash 
pattern. 

EnumeratePatternProc: type ■ procedure [dasliCallBacIc AcceptDashProc]; 

AcceptDasiiProc: type ■ procedure [dash, gap: Scalar, dashEnd: DasiiEnd <- flush]; 

The client should call dashCallBack for each dash-gap pair of the dash pattern, dash End 
determines the appearance of the end of the dash. 

Note: Currently, the unit of measure for dash patterns is always point regardless of the 
units in effect for the frame. 

DashEnd: type ■ {flush, extended, round}; 
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flush causes the dash to end at precisely the point at which its length indicates, extended 
causes the dash to be extended by half its width in the direction of the trajectory at that 
point, round causes the the dash to appear with a semicircular end, whose diameter equals 
the line width and whose center coincides with the dash end. 

A dash style may also be created by copying an existing dash style. 

CopyDashStyle: procedure [zone: uncounted zone, dashStyle: DashStyfe] 
RETURNS [DashStyie]; 

CopyDashStyle returns a copy of dashStyle whose storage is allocated from zone. 

When a dash style is no longer required it should be destroyed, and its storage freed, using 
the following procedure. 

DestroyOashStyle: procedure [zone: uncounted zone, ptr: long pointer to OashStyle]; 

zone must be the same as that which was passed to CreateOashStyle or CopyOashStyie 
when the dash style was created. 

In order to interrogate the construction of an existing dash style, the client should call 
ReadDashStyle. 

ReadOashStyie: procedure [dashStyle: DashStyie, proc: AcceptDashProc 4- nil] 
RETURNS [DashFit]; 

The client-supplied proc is called back for each dash-gap pair in dashStyle, and the fit for 
the dash style is returned returned by ReadDashStyle. 

The equality or otherwise of two dash styles is determined using the following procedure. 

DashSty iesEquai : procedure [stylel , style2: DashStyie] returns [boolean]; 

DashStylesEquai returns true if all elements of stylel and styie2 are equal, and false 
otherwise. Note that this is not the same as comparing stylel and style2 directly, since the 
two patterns may be exactly equivalent without being one and the same. 

76.2.3.3 Default properties 

Default properties are used in the creation of forms within a frame, and comprise a global 
set of property settings not specific to any particular type of form. The client will typically 
construct a single set of default values, and use this each time a form is created by calling 
Create*. This section describes the procedures whereby the client can create and 
subsequently manipulate default properties. 

A default property record is created by calling the following procedure. 
CreateDefaults: procedure [z: uncounted zone] returns [defaultProps: DefauitProps]; 
DefaultProps: TYPE ■ long pointer to DefauitPropsObject; 
DefaultPropsObject: type; 
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CreateOefaults returns a pointer to a default property object whose value consists of the set 
of standard Pro Illustrator defaults for each group of properties. The storage for the object 
is allocated from the client-supplied zone, z. 

When a default property record is no longer required it should be destroyed, and its storage 
freed, using the following procedure. 

OestroyOefauits: procedure [defauitProps: long pointer to OefaultProps]; 

For each group of properties described under Specific Property Types in Section 76.2.3.2 
above, the client can get or set the defaults within defauitProps using the Get* and Set"* 
procedures listed below. Each Get* procedure returns a complete *PropsObject, and each 
Set* procedure takes a *Props, as appropriate. 

GetOefaultAreaProps: procedure [defauitProps: DefauitProps] 
RETURNS [AreaPropsObject]; 

SetOefauitAreaProps: procedure [ 

areaProps: AreaProps, defauitProps: DefauitProps]; 

GetDefauitGraphicProps: procedure [defauitProps: DefauitProps] 
returns [GraphicPropsObject]; 

SetDefaultGraphicProps: procedure [ 

graphicProps: GraphicProps. defauitProps: DefaultProps]; 

GetDefaultPointProps: procedure [defauitProps: DefauitProps] 
RETURNS [PointPropsObject]; 

SetDefaultPointProps: procedure [ 

pointProps: PolntProps, defauitProps: DefauitProps]; 

GetDefauitLineProps: procedure [defauitProps: DefauitProps] 
returns [LinePropsObject]; 

SetOefaultUneProps: procedure [ 

llneProps: LineProps, defauitProps: DefauitProps]; 

GetDefauitLineEndProps: procedure [defauitProps: DefauitProps] 
RETURNS [LineEndPropsObject]; 

SetDefaultLineEndProps: procedure [ 

ilneEndProps: Li neEndProps, defauitProps: DefauitProps]; 

GetDefauitTextProps: procedure [defauitProps: DefauitProps] 
RETURNS [TextPropsObject]; 

SetDefauitTextProps: procedure [ 

textProps: TextProps, defauitProps: DefauitProps]; 

After changing the frame units using SetFrameUnit, the client should update any default 
property records by calling the following procedure. 
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UpdateOefaultFrameUnits: procedure [ 

defaultProps: DefauitProps, frameUnit: FrameUnit]; 

UpdateOefaultFrameUnits will cause the values in defauitProps to be represented in 
frameUnit units, so that they are correctly interpreted in subsequent Create* operations. 

76^4 Errors 

ErrorCode: type ■ {formNotPosted, unknown}; 
Error: error [code: ErrorCode]; 

Error is raised only by UnPostForm. When the form is already unposted, Error will be 
raised with code ■ formNotPosted. Any other error causes Error to be raised with code « 
unknown. 



Viewpoint Programmer's Manual 



76 



76.3 Index of Interface Items 



Item 


Page 


Item 


Page 


AcceptOashProc: type ■ proc 


21 


EnumeratePatternProc: type ■ proc 


21 


AcceptFormProc: type ■ proc 


5 


EnumerateSubForms: proc 


12 


AddEdge: proc 


6 


Error: error 


24 


AddTrajectory: proc 


5 


ErrorCode: type 


24 


AreaProps: type 


16 


Finishlllustrator: proc 


12 


AreaPropsObject: type 


16 


FixedOrVaryIng: type 


20 


AreaTexture: type 


17 


FormHandle: type 


3 


Axis: TYPE 


10 


FormProc: type ■ proc 


12 


Boolean: type 


17 


FormType: type 


15 


Boundary Type: type 


6 


FrameBorderStyie: type 


3 


Color: TYPE 


17 


FrameBrush: type 


3 


CopyOashStyle: proc 


22 


FrameHandle: type 


3 


Copy Form: proc 


9 


FrameUnit: type 


2 


CopyFrame: proc 


3 


GetAreaProps: proc 


16 


CreateOashStyie: proc 


21 


GetBottomForm: proc 


14 


CreateOefaults: proc 


22 


GetBoundary: proc 


13 


CreateElllpse: proc 


4 


GetClusterOata: proc 


15 


CreateLlne: proc 


4 


GetDefauitAreaProps: proc 


23 


CreateParailelogram: proc 


4 


GetOefaultGraphicProps: proc 


23 


CreatePoint: proc 


4 


GetOefaultLineEndProps: proc 


23 


CreateRectangle: proc 


4 


GetOefaultLineProps: proc 


23 


CreateShape: proc 


5 


GetDefaultPbintProps: proc 


23 


CreateText: proc 


8 


GetDefaultTextProps: proc 


23 


CreateTextFromCaption: proc 


9 


GetEllipseOata: proc 


15 


CreateTextFromField: proc 


9 


GetForm Above: proc 


15 


CreateTextFfomTextType: proc 


8 


GetForm Below: proc 


15 


CreateTrajectory: proc 


5 


GetFormlype: proc 


15 


CtrlPtPlace: type 


20 


GetFrameHandle: proc 


13 


DashEnd: type 


21 


GetFrameUnit: proc 


13 


DashFit: type 


21 


GetGraphicProps: proc 


17 


DashStyle: type 


21 


GetGrldding: proc 


13 


DashStytesEquai: proc 


22 


GetLlneOata: proc 


15 


OefaultProps: type 


22 


GetLineEndProps: proc 


19 


OefaultPropsObject: type 


22 


GetLlneProps: proc 


19 


OestroyDashStyie: proc 


21 


GetParallelogramData: proc 


15 


OestroyOefaults: proc 


23 


GetParentFrame: proc 


14 


OlrectionType: type 


7 


GetPointOata: proc 


15 


eccCircle: real 


7 


GetPointProps: proc 


18 


Edge: type 


6 


GetShapeOata: proc 


15 


EdgeObject: type 


6 


GetTextData: proc 


16 


EdgeProc: type ■ proc 


12 


GetTextProps: proc 


20 


EdgeType: type 


6 


GetTopForm: proc 


14 


Enumerate: proc 


12 


GetTrajectoryData: proc 


16 


EnumerateEdges: proc 


12 


GraphicProps: type 


17 


EnumerateFormsProc: type ■ proc 


5 


GraphicPropsObject: type 


17 



76-25 



76 lUustratorlnterchangeDefs 



Item 


Page 


Item Pi 




Griddinglnfo: type 


13 


SetTextProps: proc 


2U 


GriddingObject: type 


13 


Shear: proc 


11 


GndStyle: type 


14 


Startlliustrator: proc 


2 


GridType: type 


14 


TextProps: type 


20 


HasAreaProps: proc 


16 


TextPropsObject: type 


20 


HasGraphkProps: proc 


17 


Translate: proc 


11 


HasUneEndProps: proc 


19 


TranslateMode: type 


11 


HasLineProps: proc 


18 


undefinedAreaProps: AreaPropsObject 


17 


HasPointProps: proc 


18 


undefinedAreaTexture: AreaTexture 


17 


HasTextProps: proc 


20 


undefinedGraphicProps: GraphicPropsObject 


18 


Join: PROC 


5 


undefinedLineEndProps: UneEndPropsObject 


20 


LineEnding: type 


19 


undefmedLineProps: LinePropsObject 


19 


LineEndProps: type 


19 


undefinedPointProps: PointPropsObject 


18 


UneEndPropsObject: type 


19 


undefinedScalar: Scalar 


17 


LineProps: type 


19 


undef i nedTextProps : TextPropsO bj ect 


20 


LinePropsObject: type 


19 


UnPostForm: proc 


10 


LineTexture: type 


19 


UpdateOefaultFrameUnits: proc 


24 


Locn: type 


2 






Magnify: proc 


10 






Mirror: proc 


10 






niiFormHandle: FormHandie 


3 






nilFrameHandle: FrameHandle 


9 






noAreaTexture: AreaTexture 


17 






origin: Locn 


14 






Pixels: type 


3 


■ 




PointMaricer: type 


18 






PointProps: type 


18 






PointPropsObject: type 


18 






PostFormAtTop: proc 


10 






ReadDashStyie: proc 


22 






Rotate: proc 


10 






Scalar: type 


2 






Scale: proc 


11 






SetAreaProps: proc 


16 






SetBoundary: proc 


13 






SetDefauitAreaProps: proc 


23 






SetDefauitGraphicProps: proc 


23 






SetOefaultLlneEndProps: proc 


23 






SetDefaultLineProps: proc 


23 






SetOefauitPointProps: proc 


23 






SetDefauitTextProps: proc 


23 






SetFrameUnit: proc 


13 






SetGraphicProps: proc 


17 






SetGridding: proc 


13 






SetLineEndProps: PROC 


19 






SetLineProps: proc 


19 






SetPointProps: proc 


18 







76-26 



TablelnterchangeDefs 



77.1 Overview 

TablelnterchangeDefs allows clients to read the contents of a table, create a new table, or 
add information to an existing table. This interface should be used in conjunction with 
DoclnterchangeOefs or GraphicslnterchangeOefs. 

A table is described by three sets of properties: table properties, column properties, and row 
properties. Table properties include the name of the table, a description of table headers 
and the number of columns and rows in the table; column properties include whether the 
columns are divided, and the alignment of text within the columns; and row properties 
include information about how the text is aligned within a given row. The actual content 
of a table is included with the row information. 

Most records below have spare fields for future use. When specifying values for these, it is 
important to use zero if you do not know of a correct value to use. 

All dimension values are measured in micas. Clients may use the ViewPoint interface 
UnitConversion to convert to and from mica values. 

77.1.1 Table building 

To. create a new table, the client should start by calling StartTabie. This procedure takes 
table properties and column properties as parameters, and returns a table handle. Handle 
points to Object, which is a record that contains, along with table-related data, a pointer to 
the actual table content (See section 77.2.8: Diagram of table structure). Initially, the row 
properties have default values and the table has no content; the client should initialize row 
properties and content after the call to StartTabie. 

To add content to the table, the client can pass the table handle to AppendRow, which adds 
new information to the table. When all of the rows have been added, the final step is to call 
FinishTable, which creates the final structure for the table. Once the table is created, the 
client can pass this table to the procedures in DoclnterchangeOefs or 
GraphicslnterchangeOefs to add it to a document. 

FinishTable returns a Oocinterchang«0efs.lnstance for the table, which the client can pass to 
OocinterchangeO«fs.AppendAnchoredFrame or Graphkslnt«rchangeExtra20efs.AddTabie. This 
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instance is the table frame's content; the rest of a frame's properties (like captions and 
border style) are handled by OodnterchangeOefs and Graphics! nterchangeOefs. 

To add information to an existing table, the client should call StartExistingTabie instead of 
StartTabie. This procedure also returns a table handle, which the client can then pass to 
AppendRow and FinishTabie. StartExistingTabie takes an oocint«rchang«o«fs.lnstance as a 
parameter, the client will typically call Tabi«s«i«€tionO«fs.TableFromSelection to get the 
currently selected table as a value of type oodiit«rchang«o«fs.lnstance. 



77.1.2 Table reading 

To read the contents of a table, the client typically starts by calling Enumerate. Enumerate 
takes as arguments a table object (Oocinterchangeo«fs.lnstance) and a record of three call back 
procedures: a TabieProc, a CoiumnsProc, and a RowProc. 

Enumerate will call the TabieProc and the CoiumnsPrqc once for a given table; these 
procedures obtain the table and column properties. Since the content of the table is stored 
with the rows. Enumerate will call the RowProc once for each row in the table. 

There is a also a procedure EnumerateSpecificRows, which is just like Enumerate except 
that it enumerates a specific list of rows within a table rather than the entire table. 
EnumerateSpecificRows will call the RowProc once for each row in the specified range of 
rows. 

77.2 Interface Items 

77.2.1 Table properties 

A TabiePropsRec describes the properties of a table and its headers. 

TabieProps: TYPE ■ lonq pointer to TabiePropsRec; 

TabiePropsRec: TYPE « record [ 
name: xstring. Reader, 
fiiiinByRow, 
fixedRows, 
fixedCoiumns: bool, 
numlserOfColumnSr 
numberOfRows: natural, 
visibieHeader, 
repeatHeader, 
repeatTopCaption, 
repeatBottomCaption: bool, 
borderline, 
dividerLine: Line, 

horizontaiAiignment: HeaderAiignment, 
headerVerticalAlignment: VerticalAiignment, 
topHeaderlVlargin, bottomHeaderMargin: long cardinal, 

sortKeys: SortKeys, "'"^ 
sparel: long cardinal] ; 
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ascending: bool, 
sparel: LONG cardinal]; 

The SortKeysRec contains a sequence of optional SortKeys for a table or column. A column 
must be divided-repeating in order to have sort keys„ Each SortKey contains the column's 
name, its sortOrder and whether to sort in ascending or descending order. 



If sparel is not zero, it is assumed to be an ExtraTableProps pointer. 

ExtraTabieProps: TYPE ■ long pointer to ExtraTabiePropsRec; 

ExtraTabiePropsRec: type ■ record [ 
deferOnPaginate: bool, 
sparel : long cardinal]; 

deferOnPaginate Indicates whether the pagination operation will defer the table frame to 
the next page if it will not fit on the current one. If deferOnPaginate is false, the portion of 
the table that fits on the current page will be placed there, and the remainder will appear 
on successive pages. 

sparel in the ExtraTabiePropsRec is for future use. 
ExtraTableProps Is currently defined in Tablel nterchangeExtral Def s. 

77.2.2 Column properties 

Columnlnfo: type ■ long pointer to ColumnlnfoSeq; 

ColumnlnfoSeq: type ■ record [sequence length: cardinal of Col umninfoRec]; 

ColumninfoRec: TYPE ■ record [ 

headerEntryRec: HeaderEntryRec, 
name, description: xstrmg.Reader, 
divided: bool, 
subcolumns: natural, 
repeating: bool, 
subcolumnlnfo: Columnlnfo, 
alignment: HorizontalAlignment, 

tabOffset, ~ IVIicas! (different from Docint«rchangePropsO«fs.TabStop) 

width, 

leftMargin, 

rightMargin: long cardinal, 

type: Oo€inter€hangePropsD«fs.FieldChoiceType, 

required: bool, 

language: iwiuitiNationai.Language, 
format: xstring.Reader, 
stopOnSl<ip: bool, 
range: xstring.Reader, 
length: cardinal, 
skipText: xstring.Reader, 

skipChoice: DoclnterchangePropsD«fs.SkiplfChoiceType, 
fillin: xstring.Reader, 
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name is the name of the table. 

fillinByRow determines what happens when the user presses the next key. If fiillnByRow is 
TRUE, pressing the next key advances through the table one row at a time, and the table is 
expanded by rows. In this case, the number of columns is fixed and the number of rows can 
be either fixed or varying. If fillinByRow is false, then pressing the next key advances 
through the table one column at a time, and the table is expanded by columns. In this case, 
the number of rows is fixed and the number of columns can be either fixed or varying. 
fixedRows and flxedColumns indicate whether the user can change the number of rows 
and columns in the table. 

numberOKolumns and numberOf Rows are used as hints for StartTable. 

visibleHeader indicates whether there should be a visible header at the top of the table; 
repeatHeader, repeatTopCaption, repeatBottomCaption indicates whether or not to 
repeat these Items on every page if the table occupies multiple pages. 

borderline describes the table border (not the frame border), and dividerLlne describes the 
line between the header row and the rest of the table. A line can have a width anywhere 
from one pixel to six pixels. 

Line: type ■ record [ 
linestyie: Linestyie, 
linewidth: Linewidth];. 

^ J Linestyie: type « machine dependent{ 

none(O), solid, dashed, dotted, double, broken, firstAvailabie,iastAvailable(255)}; 

Linewidth: type ■ machine dependent {w1(0), w2(1), w3(2), w4(3), w5(4), w6(5)}; 

horizontal Alignment and headerVerticalAlignment specify the alignment of the text 
within a header. 

HeaderAlignment: type ■ HorizontalAlignment [left..right]; 

HorizontalAlignment: type ■ machine OEPENOENT{Ieft(0), center(1), right(2),decimal(3)}; 

VerticalAlignment: type a machine dependent { 
fiushtop(0), centered(l), flushbottom(2)}; 

topHeaderMargin and bottomHeaderMargin specify the amount of white space that 
should appear between above and below each header element. 

SortKeys: TYPE ■ long pointer to SortKeysRec; 

SortKeysRec: type ■ record [ 
length: cardinal, 
sparel : long cardinal, 

keys: sequence maxLength: cardinal of SortKey]; 

SortKey: type > record [ 

columnName: xstring.Reader, 
sortOrder: xstring.SortOrder, 
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ascending: boou 
sparel: LONG cardinal]; 

The SortKeysRec contains a sequence of optional SortKeys for a table or column. A column 
must be divided-repeating in order to have sort keys. Each SortKey contains the column's 
name» its sortOrder and whether to sort in ascending or descending order. 

If sparel is not zero, it is assumed to be an ExtraTableProps pointer. 

ExtraTableProps: TYPE ■ long pointer to ExtraTablePropsRec; 

ExtraTabiePropsRec: type • record ( 
deferOnPaginate: bool, 
sparel : LONG cardinal]; 

deferOnPaginate indicates whether the pagination operation will defer the table frame to 
the next page if it will not fit on the current one. If deferOnPaginate is false, the portion of 
the table that fits on the current page will be placed there, and the remainder will appear 
on successive pages. 

sparel in the ExtraTabiePropsRec is for future use. 
ExtraTableProps is currently defined in TableinterchangeExtral Defs. 

77.2.2 Column properties 

Coiumnlnfo: type ■ long pointer to ColumnlnfoSeq; 

ColumnlnfoSeq: type * record [sequence length: cardinal of CoiumninfoRec]; 

ColumnlnfoRec: type a record [ 

headerEntryRec: HeaderEntryRec, 
name, description: xstring.Reader, 
divided: bool, 
subcolumns: natural, 
repeating: bool, 
subcolumnlnfo: Coiumnlnfo, 
alignment: Horizontal Alignment, 

tabOffset, - Micas! (different from Docint«rchangePropsDttfs.TabStop) 

width, 

leftMargin, 

rightMargin: long cardinal, 

type: OoclnterchangeProp$D«fs.FieldChoiceType, 

required: bool, 

language: MuitiNationai.Language, 
format: xstring.Reader, 
stopOnSlcip: bool, 
range: xstring.Reader, 
length: cardinal, 
sicipText: xstring.Reader, 

skipChoice:DocinterchangePropsDefs.SI(iplfChoiceType, 
fillin: xstring.Reader, 
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f i i I i n Runs : Doclnt«rchangePropsOef s.FontRuns, 
line: Line, 

sortKeys: SortKeys, 
sparel : long cardinal]; 

A ColumnlnfoSeq describes all the columns of a table; a ColumnlnfoRec describes one 
column in detail. Within a ColumnlnfoRec, the most complicated field is a 
headerEntryRec; all of the other fields correspond directly to the fields on the property 
sheet that the user sees. The next section discusses the header properties, and section 
77.2.4 discusses the remaining column properties. 

For a more complete description of any of these properties, see the user documentation. 

77.2.3 Column header properties 

HeaderEntryRec: type « record [ 
subHeaders: Headerlnfo, 
line: Line. 

singieLineHint: bool, 

sparel: LONG CARDINAL, 

content: EntryContent]; 

A HeaderEntryRec describes the textual content of a column header. Header text can 
contain any number of font and paragraph properties per column header. 

subHeader describes the headers for each of the subcolumns. This field is only interesting 
if the column is divided. subHeader points to a sequence that contains a HeaderEntryRec 
for each subcolumn. Each subcolumn may in turn be subdivided, in which case that 
subcolumn's HeaderEntryRec subHeader field would point to another sequence. 

Headerlnfo: TYPE ■ long pointer to HeaderlnfoSeq; 

HeaderlnfoSeq: type • record {sequence length: cardinal of HeaderEntryRec]; 

line describes the properties of line that divides the header from subheaders, line is only 
visible if the column is subdivided. 

singieLineHint is a hint that the header only contains one line of text; this makes the code 
somewhat faster by simplifying the calculation of header size. If a client specifies a 
SingieLineHint value of true for a header entry and then appends more than one line of text, 
the resulting header entry will appear one line tall even though it has more text inside. 
The user can correct this by editing the text in that header entry, which causes the entry to 
recompute its height. 

sparel is for future use. 

EntryContent: type ■ record ( 

SELECT mode: * from 

read « > [obtainlextProc: ObtalnTextProc, obtainTextOata: ObtainlextOata], 
write a > [filllnlextProc: FiillnTextProc«-NiL, dientOata: long pointers- nil], 

endcase]; 
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Figure 77. 1 Table and HeaderEntryRec for table 



ObtainTextData: TYpe[4]; 

ObtainTextProc: TYPE « proc [ObtainTextData: ObtainTextData] 
RETURNS [text: T«xtlnt«rdiang«0«fs.Text]; 

FilllnTextProc: type ■ proc [text: T«xtint«rchang«o«fs.Text,dientData: long pointer]; 

content is a variant record that describes the content for a header entry. When 
enumerating a table, all the header entries will be of the form [read(...]]. The client may 
call the ObtainTextProc for an entry to obtain a TexttnterchangeOefs.Text oljject, which may 
then be enumerated via TaxtinttrchangeOafs.EnumerateText. If the client does call an 
ObtainTextProc, TaxtinterchangeOafs.ReleaseText must be called on the returned 
T«xtint«rchangeDefs.Text object when the client is finished enumerating it. 

When creating a table, the client must set all header entries to [write[...]]. The client may 
set the filllnTextProc to a proc to be called back to fill in the entry with text- clientData will 
be passed to the client's filllnTextProc. The client may default the filllnTextProc to nil so 
that the entry will be empty. 
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77.2.4 Other column properties 

name and description are the name and description of the table as It appears in the 
property sheet. 

divided specifies whether the columns can be divided, subcoiumns is the number of 
subcolumns; repeating indicates that subcoiumns can have subrows, and subcoiumninfo Is 
the recursive description of the subcoiumns. subcoiumns, repeating, and subcoiumninfo 
are ignored if divided is false. 

alignment describes the alignment of the text within a column. 

tabOffset specifies where a decimal tab should be set, relative to the margin. tabOffset 
only applies if alignment s decimal. Like all other dimensions, tabOffset is in micas (this 
is different from a Oocint«rchang«PropsO«fs.TabStopOffset, which is measured in units of 1/72 
inch). 

width is the width of the column; leftMargin and rightMargin are the margins for the 
column. These values are also in micas. 

type indicates the type of content that will appear in a column. 

required Indicates that the entry is required, and that the user must fill it in before 
proceeding to another entry in the table. 

language affects the format of date and amount fields. It is used when items are added to 
the paragraph. 

format allows the user to define a format to which the data in the column must conform. 

stopOnSkip When the user presses skip, the skipping action should stop at the next entry in 
this column. 

range is used to define a specific range of acceptable entries for the column. Once defined, 
any entry not within the defined range is not acceptable. See the user documentation for 
information on how ranges are defined. 

length allows the user to define the maxiumum number of characters that will be accepted 
in the column entries. 

skipText and skipChoice defines the conditions under which an area may be skipped when 
the user presses next. See the user documentation for more detail. 

fillin and f iilinRuns describe the fill-in rule for the column. 

line describes the properties of the vertical line to the right of the column. 

sortKeys describes the optional sort keys for the column. 

sparel is for future use. 
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77.2.5 Row content 

RowContent: TYPE ■ long pointer to RowContentSeq; 

RowContentSeq: type > record [ 

topMargin, isottomMargin: long cardinal 4-0, 
line: Line <- [solid, w2], 

verticalAlignment: VerticalAlignment 4-flushtopr 
sparel : long cardinal 0. 

rowdata: sequence lengtli: cardinal op RowEntryRec]; 

RowContentSeq describes row properties and content. The margins are the row margins; 
line is the properties of the line separating the rows. verticalAlignment specifies the 
alignment of text within a row. sparel is for future use. rowdata describes the content. 

RowEntryRec: TYPE ■ record [ 
subRows: SubRows, 
singleLlneHlnt: bool, 
sparel : long cardinal, 
content: EntryContent]; 

A RowEntryRec describes the textual content of a given row entry. 

SubRows: TYPE m LONG POINTER TO SubRowsRec; 

SubROWSRec: TYPE ■ RECORD [ 

length: cardinal, 

sparel : long cardinal <- 0, 

rows: SEQUENCE maxLength : cardinal of RowContent]; 

SubRowsRec describes subrow properties and content. If subRows is non-NiL, then the rest 
of the RowEntryRec record is unused, since the information will be in the individual 
subrow records. 

Note that subrows may only exist if the parent column is divided. 
The remaining fields are as described for header properties. 

77.2.6 Table building operations 

77J2.6.1 Creating a new table 

StartTable: proc [ 

doc: Doclnterchang«Oefs.OOC, 
props: TableProps, 
c: Columnlnfo] 
RETURNS [h: Handle]; 
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StartTabie creates a document table in doc. props describes the properties of the table 
itself; c describes the properties of the columns^ The Handle that is returned contains a 
description of row properties and table content. 

StartTabie will raise i}ocinterchang«Oefs.Error[documentFull] if the table and header row will 
not fit in the document. If StartTabie raises this error, the table cannot be added to the 
document due to lack of storage space for structures. 

StartTabie returns a handle: 

Handle: TYPE ■ long pointer to Object; 

Object: type ■ record [ 

lOne: UNCOUNTED ZONE, 

table: Do€lnterchangeO«fs.lnstance, 

tableHeight: long cardinal, 
tableWidth: LONG CARDINAL, 
rc: RowContent, 
sparel: long cardinal, 
private: array [0..0) of word]; 

zone is the zone from which dynamic storage specific to this operation is allocated, table is 
the table itself. 

tableHeight is initially equal to the height of the header row and is updated after each call 
to AppendRow. tableHeight and tableWidth are in micas, rc points to a record used as 
temporary storage for a new row. 



77.2.6.2 Opening an existing table 

StartExistingTabie: PROC[ 

table: Doclnterchang«Oefs.lnStance, 

hi: Headerlnfo 4~NiL, 
rowPropsSource: NATURAL 4-0, 
deleteExistingRows: bool<-true, 
numberOfRowsHint: natural 4-0] 
RETURNS [h: Handle]; 

StartExistingTabie sets things up to append rows to an existing table, table is the table 
object. The table passed in to StartExistingTabie is often obtained from a call to 
Tabl«S«lectionD«fs.TabieFroniSeiection, which returns the current selection as a table. 

hi describes the desired properties for the table headers. If hi a nil then the existing 
column headers are used. 

rowPropsSource is the index of a row in the table; this is the row from which the default 
properties are taken. The rows are numbered from [0..n]. The horizontal alignment for 
each entry is taken from Hrst new paragraph character in the corresponding element of the 
first row. 
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deieteExistingRows indicates whether the implementation should delete the existing 
contents of the table before adding new information. numberOfRowsHint is a hint about 
the number of rows that the table will contain; this is for efficiency purposes. 

Like StartTable, StartExistingTable returns a Handle, which the client can then pass to 
AppendRow. 

This procedure will raise oocint«rchaiig«o«fs.Error[readonlyOoc] if the document is read- 
only. 

77.2.6.3 Appending rows 

AppendRow: pROC[h: Handle, rc: RowContent]; 

AppendRow adds the row described by rc to the table described by h. Typically, h will be a 
handle obtained from either StartTable or StartExistingTable. 

RowContent is as described in section 77.2. 5. 

77.2.6.4 Finishing a table 

FinishTable: PROC[h: Handle] 

RETURNS [ 

table: Ooclnterchang«D«fsJnstance, 
tableWidth, tabieHeight: long cardinal] ; 

The client should call FinishTable when it is through editing a table. The table that is 
returned is intended to be passed as the content argument to 
OocinterchangeDefs.AppendAnchoredFrame, or as the table parameter to 
GraphicsinterchangeExtra2Defs.AddTable. This operation deletes h.zone. tabieWidth and 
tabieHeight are in micas. 

77.2.6.5 Miscellaneous utilities 

MaxTableEtements: proc returns [natural]; 

This procedure returns an estimate of the number of table cells that could reside in a 
document that has no other types of structures within. Clients may use this value to 
estimate how big a table could be created in a document. 

OefaultFontProps: PR0C[font: Docint«rchang«Propso«fs.FontPropsl; 

DefaultParaProps: proc [para: Docint«rchang«PropsOefs.ParaProps]; 

These procedures take a properties record and fill in reasonable default values. These 
operations are similar to the ones defined in OocinterchangePropsOefs. 

GetTablePropsFromName: proc[ 
doc: DoclnterchangeOefs.DOC, 
tableName: xstring.Reader, 
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tableProps: TabieProps, 
zone: uncounted zone]; 

doc is the document from which to retrieve the properties of the table specified by 
tableName. 

tableProps.name will be NiLbut the remainder of tabieProps will contain the table's 
properties. 

If tabieProps.sortKeys is not nil, it will be allocated from zone. 

77.2.7 Table reading operations 
EnumerateTabie: proc( 

table: Oo€lnt«rchange0«fs.lnstancer 
procs: EnumProcs, 
ciientData: long pointer nil]; 

EnumProcs: TYPE ■ long pointer to EnumProcsRec; 

EnumProcsRec: type ■ record [ 
tableProc: TableProc <-NiL, 
coiumnsProc: CoiumnsProc 4-NiL, 
rowProc: RowProc^NiL]; 

To parse the contents of a table, clients call EnumerateTabie or EnumerateSpecificRows. 
EnumerateTabie takes as parameters a table handle and a record of callback procedures: 
one for table properties, one for column properties, and one for row properties. 

TableProc: type ■ proc [ 
ciientData: long pointer, 
props: TableProps] 

RETURNS [stop: BOOL *- FALSE]; 

ColumnsProc: TYPE ■ proc[ 
ciientData: long pointer, 
columns: Columnlnfo] 

RETURNS [stop: BOOL 4- FALSE]; 

RowProc: type ■ proc[ 
ciientData: long pointer. 
content: RowContent] 

RETURNS [stop: BOOL 4- FALSE]; 

Enumerate calls the TableProc and the ColumnsProc once, passing in the appropriate 
property information. Because the content of the table is stored with the rows, 
EnumerateTabie calls the rowProc once for each row in the table. 

Each of these callback procedures has a boolean return value. If stop is ever returned true, 
then the enumeration will stop. 
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EnumerateSpecif icRows: proc [ 
tr: TableRows, 
procs: EnumProcs, 
clientData : long pointer nil] ; 

TableRows: TYPE ■ record [ 

table, firstRow, lastRow: oocint«rchang«Dafs.lnstance]; 

EnumerateSpecif! cRows describes a certain subset of rows in a table. As with 
EnumerateTabie, the tabieProc and the columnsProc will each be called once to describe 
the appropriate properties; the column information will describe the columns intersecting 
the described rows. The RowProc will be called once for each row in [firstRow..iastRow]. 

77.2.8 Diagram of table structure 

Figiire 77.2 is a diagram of a table structure. RowContent is a pointer to RowContentSeq. 
table is a record that contains two pointers to the actual instance of the table. (Note that 
table itself is not a pointer.) 

77.2.9 Constants 

The following constants can be used to initialize the various table properties to reasonable 
default values. 

nullExtraTableProps: ExtraTabiePropsRec ■ [ . 
deferOnPaginate: true, 
sparel: 0]; 

nullExtraTableProps is currently defined in TableinterchangeExtral Oef s. 

nullLine: Line ■ [linestyle: solid Jinewidth: w1]; 

nullSortKey: SortKey ■ [ 
columnName: nil, 
sortOrder: standard, 
ascending: TRUE, 
sparel : 0]; 

nullCoiumninfo: ColumnlnfoRec a [ 
headerEntryRec: nullHeaderEntry, 
name: nil, 
description: nil, 
divided: false, 
subcolumns: 0, 
repeating: false, 
subcolumnlnfo: nil, 
alignment: center, 
tabOffset: 0, 
width: 2540. 
leftMargin: 0, 
rightMargin: 0, 
type: any. 



Viewpoint Programmer's Manual 77 



Handle 










Object 


zone 






table 






tableHeight tableWidth 


rc 






sparel 




private 





table 

OodnterchangeOefsJnstance 



RowContent 



RowContentSeq 



topMargin, bottomMargin 
line 

verticalAlignment 
sparel 



rowdata: SEQUENCE of 

RowEntryRec 
subRows 
singleLineHint 
sparel 
content 



Figure 77.2 Diagram of Table Structure 



required: false, 
language: USEnglish, 
format: nil, 
stopOnSkip: false, 
range: nil, 

length: 0, 
skipText: nil, 
skipChoice: empty, 
fillln: NIL. 
fillinRuns: nil, 
line: [solid, w2L 
sortKeys: nil, 
sparel: 0]; 

nullHeaderEntry: HeaderEntryRec > [ 
subHeaders: nil, 
line: [solid, w2]. 
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singleLineHint: false, 
sparel : 0, 
content: [writeH]]; 

nuilRowEntry: RowEntryRec • [ 
subRows: nil, 
singleLineHint: false, 
sparel : 0, 
content: [writeQ]]; 

nullTableProps: TablePropsRec ■ [ 
name: nil, 
fiilinByRow: true, 
fixedRows: false, 
fixedCoiumns: true, 
numberOfCoiumns: 0, 
numiserOfRows: 0, 
visibleHeader: true, 
repeatHeader: true, 
repeatTopCaption: true, 
repeatBottomCaption: true, 
borderline: [none, w1], 
dividerLine: [solid, w4], 
horizontalAlignment: center, 
lieaderVerticalAlignment: centered, 
topHeaderMargin: 0, 
bottomHeaderMargin: 0, 
sortKeys: nil. 
sparel : 0]; 

tableRowsNil: TabieRows ■ [ 

DodnterchangeO«fs.instanceNil, 
Doclnt«rchang«D«fs.instanceNil, 
oocifit«rciiang«o«fs.instanceNil]; 

tableRowsNil specifies a null value for TabieRows. This value may not be passed into 
EnumerateSpecificRows. It may be returned from one of the operations in 
TableSeiectionDef s under certain error conditions. 

77.2.10 Errors 

TableError: signal [type: ErrorType]; 

ErrorType: TYPE ■ machine oependent{ 

tableTooWide, tableTooTall, tableHeaderTooTail, firstAvailable, IastAvailable(255)}; 

tableTooWlde StartTabie will raise this error if the specified table is too 

wide to fit in the document. 



tableTooTall 



AppendRow will raise this error if the specified table is too 
tall to fit in the document. 
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tabieHeaderTooTall StartTable will raise this error if the specified headers are 

too tall. 

Do not call any Interchange operations from within a catch phrase of TabieError. 

77^ Usage/Examples 

Here is an example of a simple program that runs from the Attention Menu. It registers 
two commands: Make Table, which creates a new document with a table, and Add To 
Table, which adds four new rows to the selected table. 

DIRECTORY 



TableExample: program 

iMPORTsTabielnterchangeDefs, TableSeiectionOefs, TextlnterchangeDefs, ... s { 

tableWidth: CARDINAL = 1600; -micas 

headerMargin: cardinal = 35 * 9; -micas; margin should be 9 pixels 
rowMargin: cardinal s 100; 

< < Menu Proc for Create Table command. Creates new document, creates new table, 
appends table to document, and then adds document to desktop. > > 

MakePocument: MenuOata.MenuProc = { 
rows, columns: cardinal <~ 3; - arbitrary 

doc: DoctnterchangeOefs.Poc <~ DoclnterchangeOefs.StartCreation[ 

paginateOption: nonel.doc; 
table: OoclnterchangeDefs.lnstance s BuildSimpleTable[doc, rows, columns]; 
props: DocinterchangePropsOefs-FramePropsRecord ^ 

DocInterchangePropsDefs.nullFrameProps; 
props.frameOims [tableWidth, tableWidth]; 
[ ] <- OoclnterchangeOefs-Append Anchored Frame( 

to: doc, 

type: table, 

anchored FrameProps: ®props, 

content: table]; 
Add Fi leToOeskToptdoc] ; 
}; - MakeDocument 

< < Create table inside doc with specified number of rows and columns. 
The content will be the string "abc. " >> 

BuildSimpieTable: proc [doc: DocinterchangeOefs.Ooc, rows, columns: cardinal] 

RETURNS [table: Doclnterchange0efs.lnstance4-0oclnterchange0efs.instanceNil] s { 
h: TablelnterchangeOefs-Handle; 

contentString: XString.ReaderBody <- XString.FromSTRING["abc"L]; 
c: TabielnterchangeOefs.Columnlnfo 4-Heap.systemZone.NEw[ 

TablelnterchangeDefs.ColumnlnfoSeq[columns]]; 
props: TablelnterchangeOefs-TablePropsRec [ 

name: nil, 

fillinByRow: true, 

fixedRows: false, 

fixedColumns: true, 

numberOfColumns: columns, 

numberOfRows: rows, 

visibleHeader: true. 



77-15 



TablelnterchangeDefs 



repeatHeader: true, 
repeatTopCaption: true, 
repeatBottomCaption: true, 
borderUne: [none, w1], 
dividerUne: [solidpW4], 
horizontalAiignment: center, 
headerVerticalAlignment: centered, 
topHeaderMargin: headerMargin, 
bottomHeaderMargin: headerMargin, 
sortKeys: nil, 
sparel: 0]; 

FOR i : CARDINAL IN [O.-Columns) DO i 
c[i] ♦-TabielnterchangeOefs.nuiiColumnlnfo; 
c[ij.width tableWidth; 

ENOLOOP; 

- start creating table 

h <-TabielnterchangeOefs.StartTabie[doc: doc, props: ©props, c: c]; 
Heap.systemZone.FREE[@c]; 

- set row props and content 
h.rctopMargin «- rowMargin; 
h.rcbottomMargjn «~ rowMargin; 

FOR i: CARDINAL IN [0..rOWS) DO 

FORj: CARDINAL IN [O..coiumns) DO 
. h.rcll]4-E 

subRows: nil, 

singieLineHint: false, 

sparel: 0, 

content: [write[filllnTextProc: FilllnText, ciientOata: ©contentString]]]; 

ENDLOOP; 

TablelnterchangeDefs.AppendRow(h, h.rcl; 

ENDLOOP; 

RETURN [TabielnterchangeOefs.FinishTable[h].table]; 
}; - BuildSlmpleTable 

< < Call-back procedure that writes text into the Text field of the table. 

The text to write is specified by the ciientData argument >> 
FilllnTejct: TableinterchangeOefs.FillinTextProc = { 

<< PROC[text: TextlnterchangeDefsText, dientData: long pointer]; >> 
r: XString.Reader<-NARROw(clientData, XString. Reader]; 
TextlnterchangeOefs.AppendTextToText[ 
to: text, 
text: r, 

textEndContext: XString.unknownContext]; 
}; -FilllnText 

AddFiieToOeskTop: PROC[doc: DoclnterchangeOefs.Ooc] s { 

docFile: NSFiie.Handle 4- DoclnterchangeOefs.FinishCreation[©doc].docFile; 

refDoc: NSFile. Reference = NSFile.GetReference(docFile]; 

refDt: NSFile. Reference = StarOesktop.GetCurrentDesktopFile[]; 

fiieOt: NSFiie.Handle = NSFile.OpenByReference[refDt]; 

NSFile.lVlove[docFile, fileOtJ; 

NSFile.aose[fileDtl; 

NSFile.ClosetdocFllel; 

StarDesktop.AddReferenceToDesktop[refDocl 
}; -AddFiieToOeskTop 
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< < Menu Proc for Add To Table command. 

Just adds four new blank rows to the selected table. > > 
AddToTable: Menu Data. MenuProc = { 

h: TabieinterchangeOefs-Handle «-nil; 

table: OocinterchangeOefsJnstance s 
TableSei ecti on Oef s.Tabi eFromSei ecti on (] ; 

- if current selection is not a table, then return. Otherwise, 

-add new rows to it If doc is not editable, then return. 

IP table = OoclnterchangeOefs.instanceNII THEN RETURN 

else{ 

h *- TablelnterchangeOefs.StartExistingTable[ 
table: table, deieteExistingRows: false - catch error if doc is not editable 
I TablelnterchangeOefs-TableError = > goto Exit]; 

THROUGH (0..4) DO 

TablelnterchangeDefs.AppendRow[h, h.rc]; 

ENOLOOP; 

}; 

[] <- TableinterchangeOefs. FinishTabie[h]; 

EXITS Exit = > null; 
}; -AddToTable 

Init: PROC = { 

makeTabie: XString.ReaderBody «- XString.FromSTRING["MakeTable"L]; 
addToTable: XString.ReaderBody 4-XString.FromSTRING["AddToTable"L]; 
Attenti on . Add Menu Item ( 
MenuData.Createltem[ 

zone: Heap.systemZone, 

name: ©makeTabie, 

proc: MakeOocument]]; 
Attentioh.AddMenultem[ 
Menu Data. Createltem[ 

zone: Heap.systemZone, 

name: ©addToTable, 

proc: AddToTable]]; 
}; "Init 

InitU; 
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77.4 Index of Interface Items 



Item Page 

AppendRow: proc 10 

Columnlnfo: type 4 

ColumninfoRec: type 4 

ColumnlnfoSeq: type 4 

ColumnsProc: TYPE 11 

OefauitFontProps: proc 10 

OefauitParaProps: proc 10 

EntryContent: type 5 

EnumerateSpecificRows: proc 12 

EnumerateTabie: proc 11 

EnumProcs: TYPE 11 

EnumProcsRec: type 11 

ErrorType: type 14 

ExtraTabieProps: type 4 

ExtraTabiePropsRec: type 4 

FilllnTextProc: type 6 

FinishTabie: proc 10 

GetTabiePropsFromName: pro^ 10 

Handle: type 9 

HeaderAiignment: type 3 

HeaderEntryRec: TYPE 5 

Headerlnfo: type 5 

HeaderlnfoSeq: type 5 

HorizontaiAlignment: type 3 

Line: type 3 

Linestyle: type 3 

Linewidth: type 3 

MaxTableElements: proc 10 

nullColumninfo: ColumninfoRec 12 

nullExtraTableProps: ExtraTabiePropsRec 12 

nuilHeaderEntry: HeaderEntryRec 13 

nuilLlne: Line 12 

nuilRowEntry: RowEntryRec 14 

nuilSortKey: SortKey 12 

nuilTableProps: TabiePropsRec 14 

Object: type 9 

ObtainTextOata:TYPE 6 

ObtainTextProc: type 6 

RowContent: type 8 

RowContentSeq: type 8 

RowEntryRec: TYPE 8 

RowProc:TYPE 11 

SortKey: type 3 

SortKeys: type 3 

SortKeysRec: type 3 

StartExistingTable: proc 9 

StartTable: proc 8 



Item 


Page 


SubRows: type 


8 


SubRowsRec: type 


8 


Tabie'Error: signal 


14 


TableProc: type 


11 


TableProps: type 


2 


TabiePropsRec: type 


2 


TabieRows: type 


12 


tabieRowsNil: TabieRows 


14 


VerticalAlignment: type 


3 
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78.1 Overview 

TabieSelectionOefs provides procedures to obtain the current selection as a table, or a 
selection of rows within a table. This interface is meant to be used in coi\junction with 
TabielnterchangeDefs. 

78.2 Interface Items 

TableFromSeiection: proc returns [oocint«rchangeOefs.lnstance]; 

TableFromSeiection returns the current selection as an object of type 
OoclnterchangttOefs. Instance. The client will typically pass this value to 
TableinterchangeOefs.StartExistingTabie. If the current selection is not a table, 
TableFromSeiection will retiirn DocinterchangeOefsJnstanceNii. 

TableRowsFromSeiection: proc returns [tr: Tabi«iiiter€hang«o«fs.TabieRows]; 

TableRowsFromSelection retiims the current selection as a series of rows in a table. The 
client will typically pass this value as sL parameter to 
Tableint«rchangeO«fs.EnumerateSpecificRows. If the current selection is not one or more 
table rows, TableRowsFromSeiection will return Tabi«nterchang«o«fs.tabieRowsNii. 

tableTarget: s«i«ction.Target; 

tableRowsTarget: s«i«ction.Target; 

TableFromVaiue: proc[v: s«iection. Value] 

RETURNS [OoclnterchangeOef S.I nstance] ; 

TabieRowsFromVaiue: proc [v: sei«ction. Value] 

RETURNS [tr: Tabl«lnterchangeOefs.TableRows]; 

tableTarget, tableRowsTarget, TableFromVaiue and TabieRowsFromVaiue are not 

currently implemented. 
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GetHostDocAccess: proc [instance: Oodnter€hangeO«fs.lnstance] 
RETURNS [Accessl; 

Access: type ■ machine dependent {readOnly(0),readWriter (255)}; 

Access specifies whether or not the document is in edit mode. 
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TabieFromSeiection: proc 
TableFromValue: proc 
TableRowsFromSeiection: proc 
TableRowsFromValue: proc 
tabieRowsTarget: s«i«ction.Target 
tabieTarget: s«i«ction.Target 



Item 



Page 



Access: type 

GetHostOocAccess: proc 



2 
2 
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79.1 Overview 

TextlnterchangeDefs provides procedures to create and enumerate text that resides in 
locations that DocinterchangeOefs does not define. This interface Is used by 
GraphicslntarchangeOefs to handle the content of nested text frames and by 
TablelnterchangeOefs to handle the content of header and row entries. 
TextlnterchangeDefs also provides procedures to handle the content of anchored text 
frames. 

All dimensions are in micas. Most records below have spare fields for future use. When 
specifying values for these, it is important to use zero if you do not know of a correct value 
to use. 

79.2 Interface Items 



79.2.1 Datatypes 

The basic data structure of TextlnterchangeDefs is Text, which is a pointer to an opaque 
text-containing object. 

Text: TYPE ■ LONG POINTER TO TextObject; 

TextObject: type; 

TFrameProps specify the properties of anchored text frames. Appending and enumerating 
text frames is covered later in this chapter. 

TFrameProps: type ■ long pointer to TFramePropsRec; 

ReadonlyTFrameProps: TYPE m long pointer to readonly TFramePropsRec; 

TFramePropsRec: type » record [ 
innerMargin: long cardinal, 
HiMr^ name, description: xstring.Reader, 

spare 1 : long cardinal]; 
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innerMargin is the uniform spacing between the text and the frame border. The client can 
vary the innerMargin within [0..2641 micas ([0..71 pixels). 

name and description are the name and description of the text frame as they appear in the 
property sheet. 

The sparel field can be a pointer to a TFrameExtraPropsRec (see below). These extra 
properties are active only for text frames, not form fields. So on enumeration, the sparel 
field for form fields will be 0; on creation, form field sparel is ignored. When a text frame is 
encountered during enumeration, sparel will always be non-0, and may be LOOPHOLEd into 
a ReadonlyTFrameExtraProps. During creation, the implementation assumes that if a 
sparel field is non-0, it should be treated as a ReadoniyTFrameExtraProps pointer. If it is 
0, the implementation will use default values for the extra properties. These defaults come 
from the nullTFrameExtraProps constant. 

TFrameExtraProps: TYPE • LON<j POINTER TO TFrameExtraPropsRec; 

ReadoniyTFrameExtraProps: type ■ long pointer to readonly TFrameExtraPropsRec; 

TFrameExtraPropsRec: type ■ record [ 
orientation: Orientation, 
lastLineJustify: boolean, 
autoHyphenate: boolean, 
spareO: packed array [3..1 5] of cardinal [0..1], 
sparel: LONG cardinal]; 

Orientation: type « {horizontal, vertical}; 

orientation indicates whether the text in the frame fiows horizontally or vertically. Only 
Japanese text fiows vertically. 

lastLineJustify is only used in linked text frames. It specifies whether the last line of text 
in the frame is justified. 

autoHyphenate is only used in linked text frames. It specifies whether the text in the 
frame is auto-hyphenated. 

spareO and sparel are for future use. They should be set to 0. 

All of these extra properties are currently defined in TextlnterchangeExtral Defs. 

nullTFrameExtraProps: TFrameExtraPropsRec ■ [ 
orientation: horizontal, 
lastLineJustify: false, 
autoHyphenate: false, 
spareO: all [0], 
sparel: 0]; 

nullTFrameProps: TFramePropsRec ■ [ 
innerMargin: 141, -4 pixels 
name: nil. 
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description: nil, 
sparel: 0]; 

nullTFrameProps provides default initialization values for the TFramePropsRec. 

79.2.2 Creating an Anchored Text Frame 

StartTextlnAnchoredFrame is used to begin appending text to the body of an anchored text 
frame. After an anchored text frame has been appended to a document via 
oocint«rchang«o«fs.AppendAnchoredFrame, StartTextlnAnchoredFrame may be called to 
permit text to be appended to its body. 

StartTextlnAnchoredFrame: proc[ 
dOC:Ooclnt«rchang«0«fs.Ooc, 
anchoredFrame : Docinterchang«oefs.i nstance, 
props: ReadoniyTFrameProps] 
RETURNS [text: Text]; 

doc is the document containing the new anchored text frame. 

anchoredFrame is the oo<int«rchang«D«fs. Instance returned by the call to 
Docint«rdiang«D«f$.AppendAnchoredFrame.< 

79.2.3 Append Operations 

The following append"*" procedures are similar to the ones found in OoclnterchangeOefs; 
the only difference is that these procedures append to Text objects. 

AppendCharToText: PR0C[ 
to: Text, 

char: xchar.Characterr 

fontProps: Docint«rchang«PropsOefs.ReadonlyFontProps 4-nil, 
nToAppend : cardinal 1 ]; 

AppendChar appends one or more copies of the text character char to the specified Text 
object. nToAppend specifies the number of copies of the character that are to be appended; 
fontProps specifies the character properties. 

AppendFieldToText: proc[ 
to: Text, 

fteidProps:oodnterchangePropso«fs.ReadoniyFieldProps, 
fontProps: Docinterchang«PropsD«fs.ReadoniyFontProps 4- nil] 

RETURNS [field :DoclnterchangeD«f s.Fieid]; 

AppendFleld appends a field to the specified Text object. AppendFieldToText returns a 
field; the client can then add information to the field by using the Field as a 
Doclnterchang«D«fs.TextContainer in other calls to DodntarchangaOafs.Append'* routines. 
When the client is through with the field, it must release it via 
Ooclnt«rchangeDef$.ReleaseField. 
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Note that the client cannot set the fill-in order of the fields when they are appended to the 
document. This may be done via oocinterchangaOefs-AppenditemToFiiilnOrder. 

AppendNewParagraphToText: proc[ 
to: Text, 

paraProps: Doctnt«rchang«Propso«fs.ReadonlyParaProps ^-'Nil, 
fontProps: oodnt«r€hang«PropsD«fs.ReadoniyFontProps 4- nil, 
nToAppend: cardinal 4-1]; 

AppendNewParagraphToText appends one or more newParagraph characters to a Text 
object. nToAppend specifies the number of characters to be appended. paraProps and 
fontProps specify the properties for the paragraph. If paraProps is nil, the new paragraph 
inherits the properties of the previous paragraph; however if this is the first new 
paragraph in the Text object, then it will have default properties. 

Note that Text objects always contain at least one newParagraph character. The client 
does not have to provides these initial newParagraph characters; the Textfnterchange 

implementation supplies them as required, although the client is free to append them 
anyway. The implementation ensures that if the client appends one at the start of the Text 
object, two won't appear. The client's paragraph and font properties on the newParagraph 
they appended will have precedence. 

• 

AppendTextToText: PR0C[ 
to: Text, 

text: xstring.Reader, 
textEndContext: xstring.Context, 

fontProps: OodnterchangePropsOefs.ReadonlyFontPropS 4-nil]; 

AppendTextToText appends the text with the specified properties to the Text object. For 
efficiency, the client should pass the appropriate textEndContext if it is known (just like 
xstring.AppendReader). text may not contain newParagraph characters ([set: 0, code: 
35B]). Use AppendNewParagraphToText to append these. 

AppendTileToText: PROC[ 
to: Text, 

type: Atom.AT0M, 

data : long pointer <- nil, 

fontProps: DodnterchangePropsD«fs.Readonly FontProps 4- nil] 
RETURNS [tile: OoclntarchangaOafs.Tile]; 

AppendTileToText is for future use. The tile type and data format are defined elsewhere, 
agreed upon by parties on either side of this interface. 

79.2.4 Enumeration 

To extract the content of a text object, clients call EnumerateText. 

EnumerateText: proc [ 
text: Text, 

procs: TextEnumProcs, 
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dientOata: long pointers- nil] 
RETURNS [dataSkipped: boolean]; 

procs is a pointer to a record containing client defined call-back procedures; these 
enumerate the various kinds of structures that can be found in text. 

dientOata is a client defined argument that will be passed to each of the call-back 
procedures. 

TextEnumProcs: TYPE ■ long pointer to TextEnumProcsRecord; 

TextEnumProcsRecord: TYPE « record! 

fieldProc: Docint«rchang«PropsD€fs.FieldProc 4- nil, 
newParagraphProc: ooctnt«rchangePropsOefs.NewParagraphProc ^nil, 

textPrOc: OoclnterchangePropsO«fs.TextPrOC *- NIL, 
tileProc: oocint«rchang«PropsD«fs.TileProc «~ nil]; 

TextForAnchoredFrame is used when a client wants to enumerate the body of an anchored 
text frame. 

TextForAnchoredFrame: PROC( 

doc: Oodntercliang«PropsDefs<Ooc» 
content: Do€lntttrchangePropsO«fs.lnstance, 
props: TFrameProps] 
RETURNS [text: Text]; 

doc is the document containing the anchored text frame to enumerate and content is the 
value passed to the OocinterchangeOefs.AnchoredFrameProc. The Text object that is returned 
may be passed to EnumerateText. After enumerating the text, the client must call 
ReleaseText on the text object returned by TextForAnchoredFrame. 

TextForAnchoredFrame fills in props with text specific properties of the frame. 

79.2.5 Releasing Text 

The client should release the text object after calling StartTextlnAnchoredFrame or 
TextForAnchoredFrame. 

ReleaseText: proc [textPtr: long pointer to Text]; 

79.2.6 Text Frame Link Order 

This section discusses the data types and operations related to the text frame link order of a 
document. Every document may have an optional text frame fill-in order which defines the 
order in which text is poured into frames by pagination and by the 'Till Text Frames" 
command. This fill-in order is similar to the one for fields and tables. 

All of the items declared in this section are currently defined in 
TextlnterchangeExtral Def s. 

TextLinkitem: type * long pointer to readonly TextLinkitemRec; 
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TextLinkltemRec: type « record [ 
name: XString.Reader, 
sparel : long cardinal]; 

Specifies an item in the linked text frame order. 

TextLinkEnumProc: type ■ PROC[item: TextLinkltem^clientData: long pointer] 

RETURNS [stop: BOOL <- FALSE]; 

Callback proc for enumerating the text frame link order. See EnumerateTextLink. 
EnumerateTextLink: proc [ 

doc: OcKlnt«rchang«0«fs.OOC« 

proc: TextLinkEnumProc, 

ci i entData : long pointer nil] ; 

Enumerates the text frames in the text frame link order. 

ClearTextLink: proc [doc: Dodnt«rchang«o«fs.Ooc]; 

Clears the text frame link order of the document. May be called at any time. Usually 
called once just before a series of calls to AppendltemtoTextLink. 

AppendltemToTextLink: proc [ 

doc: Ooclnt«rcliange0«fs.0oc, 

item: TextLinkitem]; 

Appends an item (a text frame) to the text frame link order. May be called at any time. 

79.3 Example 

The proper sequence of calls to append an anchored text frame having content is: 

props: TextlnterchangeDefs. TFramePropsRec [...]; 

[anchored Frame, ...] OocinterchangeOefs.AppendAnchoredFrame[ 

to: doc, type: text, ...]; 
text <-TextlnterchangeDefs.StartTextlnAnchoredFrame[doc, anchored Frame, ©props); 
TextlnterchangeDefs.AppendTextToText(text, reader, ...]; 
TextlnterchangeOefs.ReleaseText[@text]; 

It is not mandatory that the client call StartTextlnAnchoredFrame after appending an 
anchored frame. Failing to call StartTextlnAnchoredFrame simply means that the 
anchored text frame will be empty, except for one new paragraph character that has 
default paragraph and font properties. Note that if the client does not call 
StartTextlnAnchoredFrame, then the client should not call ReieaseText. 
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79.4 Index of Interface Items 

Item Page 

AppendCharToText: proc 3 

AppendFieidToText: proc 3 

AppendltemToTextLink: proc 6 

AppendNewParagraphToText: proc 4 

AppendTextToText: proc 4 

CiearTextLink: proc 6 

EnumerateText: proc 4 

EnumerateTextLink: proc 6 
nuilTFrameExtraProps: TFrameExtraPropsRec 2 

nuilTFrameProps: TFramePropsRec 2 

Orientation: type 2 

ReadonlyTFrameExtraProps: TYPE 2 

ReadonlyTFrameProps: type 1 

ReieaseText: proc 5 

StartTextlnAnchoredFrame: proc 3 

Text: type 1 

TextEnumProcs: type 5 

TextEnumProcsRecord: type 5 

TextForAnchoredFrame: proc 5 

TextLinkEnumProc: type 6 

TextUnkltem: TYPE 5 

TextLinkltemRec: type 6 

TextObject: type 1 

TFrameExtraProps: type 2 

TFrameExtraPropsRec: type 2 

TFrameProps: type 1 

TFramePropsRec: type 1 
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Appendix A 



System KeyNames and TIP Tables 



A.l -Overview 

This appendix contains generally useful information about how ViewPoint "sees" keys at 
the stimulus level and at the TIP level. 

§A.2 lists KeyNames in terms known to level4 (dlion) and level5 (daybreak) stimlev, TIP 
names known to both the XDE and BWS world, and how all these relate to each other. The 
XDE comparison is designed to help the programmer who programs in both worlds and/or 
converts XDE tools to ViewPoint tools. 

§A.3 deals with some TIP predicates that ViewPoint registers at boot time. These useful 
predicates may be used by clients as well as the BWS. For more information on 
TIP. Predicates see the TIP chapter Semantics of Tables. 

The system TIP tables ViewPoint uses are listed to provide the programmer with a list of 
the productions available in the general-purpose tables. The Normal tables described in 
§A.4.1 are placed in the TIPStar watershed at boot time and are therefore available for use 
by application programs. (See the TIPStar interface for further information about the 
TIPStar watershed.) Clients are encouraged to use the productions in the Normal tables 
whenever possible rather than generating new tables. Examples of use are provided in 
§A.5. 
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A System TIP Tables 



A.2 KeyNames/TIP name mapping 



LevelIVKeys.KeyName 


Level VKeys.KeyName 


BWS TIP name 


XDE TIP name* (if 




(if different from LevellV) 




different from BWS) 


notAKey(0) 


nulKO) 


"null" 


0 




Bullet(l) 


"Bullet- 


+ 




SuperSub(2) 


"SuperSub" 


+ 




CaseCS) 


"Case" 


+ 




Strikeout(4) 


"Strikeout" 






KeypadTwo(5) 


"KeypadTwo" 


+ 


- 


KeypadThree(6) 


"KeypadThree" 


+ 




SingleQuote(7) 


"SingleQuote" 


+ 


KeysetKS) 


KeypadAdd(8) 


"KeypadAdd" 


+ 


Keyset2(9) 


Ke3rpadSubtract(9) 


"KeypadSubtract" 


+ 


KeysetSdO) 


KeypadMultiply(lO) 


"KeypadMultiply" 


+ 


Keyset4(ll) 


KeypadDivided 1) 


"KeypadDivide" 


+ 


Keyset5(12) 


KeypadClear(12) 


"KeypadClear" 




MouseLefldS) 


Point(13) 


"Point" 




MouseRight(14) 


A4iust(14) 


"Adjust" 




MouseMiddle( 15) 


Menu(15) 


"Menu" 




Five(16) 




"Five" 




Four(17) 




"Four" 




Six(18) 




"Six" 




E(19) 








Seven(20) 




"Seven" 




D(21) 




"D" 




U(22) 




"U" 




V(23) 








Zero(24) 




"Zero" 




K(25) 




"K" 




Miniis(26) 


Dash(26) 


"Dash" 




P(27) 




HpN 




SIash(28) 




"Slash" 




Font(29) 




"FONT" 


"Backslash" 


SameOO) 




"SAME" 


"PASTE" 


BS(31) 




"BS" 




Three(32) 




"Three" 




Two(33) 




"Two" 




W(34) 




"W" 




Q(35) 




"Q" 




S(36) 




"S" 




A(37) 




"A" 




Nine(38) 




"Nine" 




1(39) 








X(40) 




"X" 




0(41) 




HQI. 




L(42) 




"L" 




Comma(43) 




"Comma" 




CloseQuote(44) 


Quote(44) 


"Quote" 


# 


RightBracket(45) 




"RightBracket" 




Open(46) 




"OPEN" 


"STUFF" 
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LeveiIVKeys.KeyName 


Le vei VKey s. Key Name 


BWSTIP name 


XDE TIP name * (if 




(if different from LevellV) 




different from BWS) 


Keyboard(47) 


Special(47) 


"SPECIAL" 


"COMMAND" 


One(48) 




"One" 




Tab(49) 




"TAB" 


"COMPLETE" # 


ParaTab(60) 




"PARATAB" 


"TAB" 


P(51) 




Npn 




Props(52) 




"PROPS" 


"CONTROL" 


C(53) 




•*C" 




J(54) 








B(55) 




"B" 




Z(56) 




**Z" 




LeftShift(57) 




"LeftShift" 




Penod(58) 




"Period" 




SemiColon(59) 




"SemiColon" 




NewPara(60) 




"NewPara" 


"Return" 


OpenQuote(61) 




"OpenQuote" 


"Arrow" # 


Delete(62) 




"DELETE" 




Next(63) 




"NEXT" 




R(64) 




K 




T(65) 








G(66) 




"G" 




Y(67) 








H(68) 




"H" 




Eight(69) 




"Eight" 




N(70) 




"N" 




M(71) 




"M" 




Lock(72) 




"LOCK" 




Space(73) 




"Space" 




LefbBracket(74) 




"LeftBracket" 




Equal(75) 




"Equal" 




RightShifl(76) 




"RightShift" 




Stop(77) 




"STOP" 


"USERABORT" 


Move(78) 




"MOVE" 




Undo(79) 




"UNDO" 




Margins(80) 




"MARGINS" 


"DOIT" 


R9(81) 


Ke3rpadSeven(81) 


"KejrpadSeven" 


+ 


L10(82) 


KeypadEight(82) 


"KeypadEight" 


.+ 


L7(83) 


KeypadNme(83) 


"KeypadNine" 


+ 


L4(84) 


KeypadFour(84) 


"KeypadFour" 


+ 


Ll(85) 


KeypadFive(85) 


"KeypadFive" 


+ 


A9(86) 


English(86) 


"English" 


J 


R10(87) 


KeypadSix(87) 


"KeypadSlx" 


+ 


A8(88) 


Katakana(88) 


"Katakana" 


J 


Copy(89) 




"COPY" 




FindOO) 




"FIND" 




AgainOl) 




"AGAIN" 




Help(92) 




"HELP" 


# 


Expand(93) 




"EXPAND" 




R4(94) 


KeypadOne(94) 


"KeypadOne" 


+ 
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System TIP Tables 



LevelIVKeys.KeyName 

D2(96) 

Dl(96) 

Center(97) 

Tl(98) 

Bold(99) 

ItaUcsdOO) 

Underline(lOl) 

Superscript(102) 

SubscriptdOS) 

Smaller(104) 

T10(106) 

R3(106) 

Key47(107) 

A10(108) 

Defaults(109) 

AlKllO) 

A12(lll) 



Level VKeys.KeyName 
(if different from LevellV) 
DiagnosticBitTwo(95) 
DiagnosticBitOne(96) 

KeypadZero(98) 

Italic(lOO) 



KeypadPeriod(105) 
KeypadComma( 106) 
LeftShiitAltdO?) 
DoableQuotedOS) 

HiraganadlO) 
RightShiftAItdll) 



BWS TIP name 

"DiagnosticBitTwo" 

"DiagnosticBitOne" 

"CENTER- 

"KeypadZero" 

-BOLD- 

TTALICS" 

"UNDERLINE- 

"SUPERSCRIPT- 

"SUBSCRIPT- 

"SMALLER- 

"KeypadPeriod" 

"KeypadComma" 

"LeftShiftAlt" 

"DoubleQuote" 

"DEFAULTS" 

"Hiragana" 

"RightShiflAlt" 



XDE TIP name* (if 
different from BWS) 

0 

0 

"MENU" 

+ 

"SCROLLBAR" 
"JFIRST" 
"JSELECT" 
"RESERVED" # 
"CLIENTl" # 
"CLIENT2" 

+ 

+ 

J 

+ 

"ATTENTION" # 
J 
J 



*Key: (0 not on any keyboard) (JJStaronly) (+ daybreak only) (# dandelion only) 

Viewpoint Registered TIP.Predicates 

You will notice in the following tables the use of several TIP.Predicates. These predicates 
are registered by ViewPoint at boot time and are available for use by clients as well as the 
system. Most of these predicates are used to dertermine within a TIP.Table which physical 
keyboard is attached to the workstation. The following is the list of predicate. atoms and 
their meaning. See the Normal tables themselves for examples of use. For more 
information about TIP.Predicates see §47.3.3 Predicateldent. 

Ievel4 matches any of the DLion keyboards 

(American, European or Japanese) 

aLevel4 American DLion keyboard 

eLevel4 European DLion keyboard 

jLevel4 Japanese DLion keyboard 

levels matches any of the Daybreak keyboards 

(American, European or Japanese) 

aLeveiS American Daybreak keyboard 

eLevelS European Daybreak keyboard 

jLevelS Japanese Daybreak keyboard 

cursorKeys keypad on Daybreak or sideKeys on Dlion is producing cursorKeys 
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A.4 Tables 

A.4.1 Normal Tables 

The set of Normal tables ( Normal Mouse.TIP, NormalSoftKeys.TIP, Normal Key board.TIP, 
NormaiSideKeys.T1P, NormaiBackstop.TIP) are registered at startup and pushed into the 
list of TIP tables at the appropriate TIPStar placeholder (mouseActions, softKeys, 
blackKeys, sideKeys, backstopSpecialFocus). (See TIPStar for further explanation about 
placeholders.) The set of Normal tables provides productions for all possible user input. 
Table entries are divided up into logical groups corresponding to the placeholder the table 
will be pushed onto. Thus input actions pertaining to the mouse (Point Down, Adjust 
Down, etc.) appear in the Normal Mouse.TIP table and Normal Mouse.TIP is pushed onto the 
mouseActions placeholder. Key actions from the side fimction key group that are directed 
at the input focus (MOVE Down, COPY Down, etc.) appear in the NormalSideKeys.TIP table 
and are pushed onto the sideKeys placeholder. Key actions such as the alphanumeric keys 
(A Down, 3 Down, etc.) appear in the NormalKeyboard.TIP table and are pushed onto the 
blackKeys placeholder. Key actions pertaining to the row of function keys at the top of the 
keyboard (CENTER Down, BOLD Down, etc.) appear in the NormalSoftKeys.TIP table and are 
pushed onto the softKeys placeholder. Key actions from the side function key group that 
are not directed at the input focus (KEYBOARD Down, HELP Down) appear in the 
NormalBackstop.TIP table and are pushed onto the backstopSpecialFocus placeholder. 

At the end of ViewPoint boot sequence, the list of TiP.Tables in ViewPoint will appear as in 
Figure A-1. 



A 



System TIP Tables 



mouseActions placeholder 



NormalMouse.TlP 



keyOverrides placeholder 



J 



softKeys placeholder 



NormalSoftKeys.TIP 



keyboardSpecific placeholder 



T 



keyboardplaceholder 



NormalKeyboard.TIP 



sideKeys placeholder 



NormalSideKeys.TIP 



backstopSpecial Focus placeholder 



NormalBackstop.TIP 



NIL 



Figure A.1 TIP Tables after boot 
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"File: NormalBackstop.TIP last edit: 14^Aug-a6 1 1:50:24 

[OEF,tfShift,(SELECT ENABLE FROM 
UftShiftOown ■> "1; 
RightShift Down « > '1 ; 

K«y47 Down » > ~1 ; ~ JLevellV keyboard LeftShiftAit 
A1 2 Down « > '1 ; - JLevellV keyboard RightShiftAlt 

ENOCASE ■ > *2)] 
SELECT TRIGGER FROM 

FONT Down WHILE Ievel4 « > [lfShlft,ShiftFontOown,FontDown]; 
FONT up WHILE Ievel4 M > [IfShift^ShiftFontUprFontUp]; 
KEYBOARD Down « > [lfShift,ShiftKeyboardOown,KeyboardDown]; 
KEYBOARD Up ■ > [lfShlft,ShiftKeyboardUp,KeyboardUp]; 
HELP Down WHILE Ievei4 m > [lfShift,ShlftHelpOown,HeipDown]; 
HELP Up WHILE ievelA « > [lfShift,ShlftHelpUp,HelpUp]; 
STOPDown • > [lfShlftShlftStop,Stop]; 
STOPUp «> [ifShift,ShiftStopUp,StopUp]; 
UNDO Down * > (If Shift,ShiftUndoOown,UndoOown]; 
UNDO Up « > [lfShift,ShiftUndoUp,UndoUp]; 

ENDCASE... 
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-File: NormalKeyboard.TIP /ast ec//t; 4-Mar'86 18:38:49 

[OEFjf Shift.(SELECT ENABLE FROM 
LeftShiftOown ■>^1; 
RightShift Down M>'*^^; 
K«y47 Down a > SELECT ENABLE FROM 

jLevei4 « > *1 ; - JLeveilV keyboard 
jLeveiS « > '1; - JLevelV keyboard 
A12 Down • > ~ 1 ; " JLeveUV keyboard 
ENOCASE m > ^2)1 



SELECT TRIGGER FROM 



BS Down ■ > [IfShift, BackWord, Backspace]: 
Return Down ■ > pfShift, NewLine, NewParagraph]; 

Buikt Down m > BUFFEREDCHAR: -ieveiV (nofi-existent on ieveilV keyboard) 
singieQuoie Down « > BUFFEREDCHAR: -ievelV (non-existent on IeveilV keyboard) 



- use predicates to distinguish physical keyboards 
K«y47 Down • > SELECT ENABLE FROM -LeftShiftAlt in level V terminology 
eLevel4 a > bufferedchar; -European keyboard uses this as char key 
eLeveiS > > bufferedchar; -Japanese keyboard uses this as shift key 
ENOCASE « > LeftShiftAltDown: -The key is non-existent on Amer keyboard 

Z«roDown « > BUFFEREDCHAR: 
0n« Down a > BUFFEREDCHAR; 
Two Down M > BUFFEREDCHAR; 
Three Down * > BUFFEREDCHAR; 
Four Down « > BUFFEREDCHAR; 
Fivo Down « > BUFFEREDCHAR: 
Six Down a > BUFFEREDCHAR; 
Seven Down - > BUFFEREDCHAR; 
Eight Down « > BUFFEREDCHAR; 
Nine Down * > BUFFEREDCHAR: 



A Down a > BUFFEREDCHAR: 
BDown a > BUFFEREDCHAR: 
CDown a > BUFFEREDCHAR; 
D Down a > BUFFEREDCHAR: 
E Down a > BUFFEREDCHAR: 
F Down a > BUFFEREDCHAR; 
6 Down a > BUFFEREDCHAR; 
H Down a > BUFFEREDCHAR; 
I Down a > BUFFEREDCHAR: 
J Down a > BUFFEREDCHAR; 
K Down a > BUFFEREDCHAR; 
L Down a > BUFFEREDCHAR; 
M Down a > BUFFEREDCHAR: 
N Down a > BUFFEREDCHAR; 
O Down a > BUFFEREDCHAR; 
PDown a > BUFFEREDCHAR; 
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Q Down a > BUFFEREDCHAR; 
ROown a > BUFFEREDCHAR; 
SOown « > BUFFEREDCHAR: 
TOown » > BUFFEREDCHAR: 
U Down m > BUFFEREDCHAR; 

V Down m > BUFFEREDCHAR; 
WDown > > BUFFEREDCHAR; 
XDown m > BUFFEREDCHAR: 

Y Down m > BUFFEREDCHAR: 
ZDown m > BUFFEREDCHAR: 

aoMQuotoDown « > BUFFEREDCHAR; 

DouWoQuoteDown * > BUFFEREDCHAR: -ievelV (A10 was unused on levellV) 

Comma Down « > BUFFEREDCHAR; 
Minus Down m > BUFFEREDCHAR: 
Equal Down • > BUFFEREDCHAR: 
LaftBracfcatDown « > BUFFEREDCHAR: 
Period Down « > BUFFEREDCHAR; 
OpanQuota Down « > BUFFEREDCHAR: 
RightBraclcatDown ■ > BUFFEREDCHAR; 
SamlColon Down m > BUFFEREDCHAR; 
Spaca Down « > BUFFEREDCHAR; 
Stash Down » > BUFFEREDCHAR; 

- use predicates to distinguish physical keyboards 

PARATAB Down «> SELECT ENABLE FROM 

eLevel4 » > [If Shift, TabOown, ParaTabOown]; 
levels a > [IfShift, TabOown, ParaTabOown]; 
ENOCASE > > ParaTabOown; 

TAB Down n > SELECT ENABLE FROM 

eLevel4 « > bufferedchar; 

levels » > BUFFEREDCHAR: 

ENDCASE M >TabOown; 

LOCK Down » > LockOown; 
LOCKUP «> Lockup: 

-JStar keyboards 

- Note: A8, A9, A11 , A1 2 and Key47 exist only on the J keyboards. 

All Down m > BUFFEREDCHAR; 
A8 Down m > BUFFEREDCHAR; 
A9 Down » > BUFFEREDCHAR: 

- Oiagnostics bits 

DiagnosticBitOna Down » > OiagnosticBitOneOown; -levelV(D1 was unused on leveilV) 
DiagnosticBitTwoDown « > OiagnostlcBitTwoOown; -levelV (02 was unused on leveilV) 



ENDCASE.. 
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-FfVe: NormailVIouse.TIP last edit: 3- Apr-86 15:29:19 
OPTIONS Smail; 

[OEF.SHIFT.(LeftShift Down | RightShift Down | K«y47 Down | A12 Down)] 
[DEF,ChordP,(SELEa TRIGGER FROM 

'1 Down BEFORE 200 ■ > {time COORDS Menu PointOown AdjustDown}; 

ENOCASE ■ > '2 )] 
[DEFXhordA,(SELECT TRIGGER FROM 

'1 Down BEFORE 200 ■ > {time COORDS Menu AdjustDown PointOown}; 

ENDCASE ■ > '2 )] 
SELECT TRIGGER FROM 

MOUSE * > SELECT ENABLE FROM 

PointOown « > COORDS, PomtMotion; 

Adjust Down » > COORDS, AdjustMotion; 

MouMMiddle Down * > COORDS, MOUSeMiddleMotion; 
ENDCASE; 

PointOown ■ > [ChordP,Adjust, 
SELECT ENABLE FROM 

[shift] ■ > {time COORDS Menu PointOown}; 
ENDCASE ■> {time COORDS PointOown}]; 

Point up a > 
SELECT ENABLE FROM 

[shift] •> time, COORDS, Shift, PointUp; 
ENDCASE ■> time, COORDS, PointUp; 

AdjustDown ■ > [ChordA,Point, 
SELECT ENABLE FROM 

[SHIFT] m > {time COORDS Menu AdjustDown}; 

ENDCASE * > {TIME COORDS AdjustDown}]; 
Adjust Up ■ > 
SELECT ENABLE FROM 

[SHIFT] ■ > TIME, COORDS, Shift, AdjustUp; 

ENDCASE a > TIME, COORDS, AdjuStUp; 
Mous«Middio Down * > SELECT ENABLE FROM 

[SHIFT] a > TIME, COORDS, Shift, MouseMlddlcDown; 
ENDCASE M > TIME. COORDS. MouseMiddleOown; 

MouseMiddie Up » > SELECT ENABLE FROM 

[SHIFTI m > TIME, COORDS. Shift, MouseMiddleUp; 
ENDCASE « > TIME, COORDS, MouseMiddleUp: 

ENTER « > Enter; 

EXIT « > Exit; 



ENDCASE.. 
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.-F//e; NormalSideKeys.TIP last edit: 24- Apr-a? 13:37:50 

[DEPWfShift,(SELECr ENABLE FROM 
UftShift Oovtfii « > '1 ; 
RightShift Down « > "1 ; 

K«y47 Down - > ' 1 ; — JLevellV keyboard LeftShiftAlt 
A12 Down ■ > '1 ; — JLevellV keyboard RIghtShiftAlt 

ENDCASE m > '2)1 



SELECT TRIGGER FROM 

- left function keys on botit daybreak and dllon keyboards 
AGAIN Down ■ > [lfShift,ShiftAgainOown^gamOown]; 
AGAIN Up » > [lfShift,ShiftAgamUp,AgainUp]; 

DELETE Down «> [lfShift,ShiftOeieteOown,DeieteOown]; 

DELETE up a > [lfShjft,ShiftOeieteUp,OeleteUp}; 

FIND Down *> [lfShift,ShiftFindOown,FindDown]; 

FIND Up » > (lfShift,ShiftFindUp,FindUp]; 

COPYOown «> [lfShift,ShiftCopyOown,CopyDown]; 

COPY up « > [If ShiftShiftCopyUpXopyUp]; 

SAME Down « > [lfShift,ShiftSameOown,SameOown]; 

SAME Up » > [lfShift,ShtftSameUp,SameUp]; 

MOVE Down «> [lfShift,ShiftMoveOown,MoveDown]; 

MOVE up » > [If Shift,ShiftMoveUp,MoveUp]; 

OPEN Down m > [If Shift,ShiftOpenDown,OpenDown]; 

OPEN up a > [lfShift,ShiftOpenUp,OpenUp]; 

PROPS Down >> [lfShift,ShiftPropsOown,PropsOownI; 

PROPS Up -> [lfShift,ShiftPropsUp,PropsUp]; 

- beside space bar on daybreak and in right function group on dlion 
EXPAND Down ■ > [lfShift,OefineOown,ExpandDown]; 

EXPAND up ■ > [lfSliift,OefineUp,ExpandUp]; 

- right function keys on both keyboards 

NEXT Down * > SELECT ENABLE FROM 

cursorKeys > > select enable from 

Ievel4 m> [lfShift,HomeDown,LeftArrowOown]; 

ENDCASE 3 > [lfShift,SkipOown,NextDown]; 
ENDCASE M > [ifShift,SkipOown,NextDown]; 

NEXT Up » > SELECT ENABLE FROM 

cursorKeys » > select enable from 

leveiA « > (lfShift,HomeUp,LeftArrowUp]; 

ENDCASE M > [lfShift,SkipUp,NextUp]; 
ENDCASE « > {lfShift.SkipUp,NextUp]; 

- part of the right function group on dlion but moved to softkeys on daybreak 

MARGINS Down WHILE Ievel4 » > SELECT ENABLE FROM 

cursorKeys » > [ifShift,EndPageOown,DwnArrowOown]; 
ENDCASE a > ClfShift.ShiftMarginsOown,MarginsOown]; 
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MARGINS Up WHILE Ievei4 » > SELECT ENABLE FROM 

cursorKeys * > [ifShift,EndPageUp,OwnArrowUp]; 
ENOCASE a > UfShift,ShiftMarginsUp,MarginsUp]; 

- Added for Cursor Keys 

HELP Down WHILE cursorKeys « > [lfShift,StartPageOown,UpArrowOown]; 
HELP Up WHILE cursorKeys - > (ifShift,StartPageUp,UpArrowUp]; 

UNDO Down WHILE Ievei4 - > SELECT ENABLE FROM 

cursorKeys ■ > (lfShift«EndDown,RightArrowOown]; 

ENOCASE; 

UNDO Up WHILE Ievei4 m > SELECT ENABLE FROM 

cursorKeys » > pfShift,EndUp,RightArrowUp]; 

ENOCASE: 



- calculator key pad on daybreak 

- (has no meaning on dlion except In virtual keypad) 

KaypadZttro Down « > BUFFEREDCHAR; 

K«ypadOn« Down « > SELECT ENABLE FROM 
levels - > SELECT ENABLE FROM 

cursorKeys » > [lfShift,BUFFEREDCHAR,EndDown]; 
ENOCASE • > (If Shift,EndDown,BUFFEREOCHAR]; 

ENOCASE * > BUFFEREDCHAR; 

K«ypad0fM Up ■ > EndUp; 

KeypadTwo Down > > SELECT ENABLE FROM 
levels M > SELECT ENABLE FROM 

cursorKeys » > [lfShift,BUFFEREDCHAR,DwnArrowOown]; 
ENOCASE » > [If Shift,OwnArrowOown,BUFFEREOCHAR]; 

ENOCASE « > BUFFEREDCHAR; 

K«ypadTwo Up « > DwnArrowUp; 

K«ypadThr«tt Down * > SELECT ENABLE FROM 
levels m > SELECT ENABLE FROM 

cursorKeys « > [lfShift.BUFFEREOCHAR,NextPageDown]; 
ENOCASE « > [lfShift,NextPageOown,BUFFEREDCHAR]; 

ENOCASE - > BUFFEREDCHAR; 
KaypadThraaUp s> NextPageUp; 

KsypadFour Down « > SELECT ENABLE FROM 
levels M > SELECT ENABLE FROM 

cursorKeys » > [lfShiftrBUFFEREOCHAR,LeftArrowOown]; 
ENOCASE » > [lfShift,LeftArrowOown,BUFFEREDCHAR]; 

ENOCASE - > BUFFEREDCHAR; 
KaypadFourUp * > LeftArrOwUp; 



KeypadFive Down - > BUFFEREDCHAR; 



Viewpoint Programmer's Manual 



A 



KeypadSix Down m > SELECT ENABLE FROM 
levels s > SELECT ENABLE FROM 

cursorKeys « > [lfShift,BUFFEREOCHAR,RightArrowOown]; 
ENOCASE * > [lfShift,RightArrowOown,BUFFEREDCHAR]; 

ENOCASE a > BUFFEREOCHAR; 

K«ypadSixUp « > RightArrowUp; 

K«ypadS«v«n Down - > SELECT ENABLE FROM 
levels - > SELECT ENABLE FROM 

cursorKeys ■ > [lfShift,BUFFEREDCHAR,HomeDown]; 

ENOCASE - > [lfShift.H0me00wn,BUFFERE0CHAR]; 
ENOCASE » > BUFFEREOCHAR; 
K«ypadS«v«n Up • > HomeUp; 

K«ypadEightOown * > SELECT ENABLE FROM 
levels M > SELECT ENABLE FROM 

cursorKeys ■ > [lfShift,BUFFEREDCHAR,UpArrowOown]; 
ENOCASE M > (lfShlft,UpArrowOown,BUFFEREDCHAR]; 

ENOCASE m > BUFFEREOCHAR; 
K«ypadEightUp » > UpArrowUp; 

K«ypadNintt Down « > SELECT ENABLE FROM 
levels * > SELECT ENABLE FROM 

cursorKeys « > [lfShift,BUFFEREOCHAR,PrevPageOown]; 
ENOCASE * > [ffShift,PrevPageDown,BUFFEREOCHAR]; 

ENOCASE M > BUFFEREOCHAR; 

K«ypadNine Up « > PrevPageUp; 

K«ypadAdd Down « > BUFFEREOCHAR; 
KaypadSubtractOown * > BUFFEREOCHAR; 
K«ypadMuitipiy Down m > BUFFEREOCHAR: 
K«ypadOivid«Oown • > BUFFEREOCHAR: 

KeypadP«riod Down « > SELECT ENABLE FROM 
levels • > SELECT ENABLE FROM 

cursorKeys » > [ifShift.BUFFEREDCHAR,StartPageDown]; 
ENOCASE s > [lfShift,StartPageOown,BUFFEREDCHAR]; 

ENOCASE - > BUFFEREOCHAR: 

K«ypadP«riod Up • > StartPageUp; 

K«ypadComma Down > > SELECT ENABLE FROM 
levels « > SELECT ENABLE FROM 

cursorKeys « > [lfShift,BUFFEREOCHAR,EndPageOown]; 
ENOCASE s > ClfShift,EndPageOown,BUFFEREDCHAR]; 

ENOCASE » > BUFFEREOCHAR; 
KeypadComma Up « > EndPageUp; 

K0ypada«arOown « > [lfShift,ShiftClearOown,ClearDown]; 
K«ypadOearUp « > [lfShlft,ShiftCIearUptCIearUp]: 

ENOCASE... 
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« f//e: NormalSofl;Keys.TIP last edit: 5- Mar-SS 12:40:42 
— SoftKeys are the top row of function l^eys 

[OEF,lfShift,(SELECT ENABLE FROM 
UftShiftOown *>'^: 
RightShiftOovwi • > '1; 

K«y47 oowm m>'^; JLevellV Iceyboard LeftShiftAlt 
A12 oown * > '1 ; - JLevellV keyboard RlghtShiftAH 

ENDCASE » > "2)] 



SELECT TRIGGER FROM 

— top function iieys 

CENTER Down ■ > [lfShift,ShiftCenterDownXenterOown]; 
CENTER up » > [lfShift.ShiftCenterUpXenterUp]; 
BOLD Down «> [lfShift,UnbolciDown,BoldDown]; 
BOLD Up « > [lfShift,UnboldUp,BoldUp]; 
ITAUCS Down « > [If Shift,ShiftltaiicsOown,ltalicsOown]; 
iTAUCSUp«>[lfShift.ShiftltaiksUp,ltalicsUp]; . 

- Case key on daybreak only 

Caso Down ■ > [lfShift,ShiftCaseOown,CaseOown]; 
Casoup ■ > [lfShift.ShiftCaseUp,CaseUp]; 

UNDERUNE Down ■ > SELECT ENABLE FROM 

Ievei4 ■ > [lfShift,ShiftUnderlineOown,UnderlineOown]; 
levels ■ > [lfShift,ShiftDbkUnderlineOown,ObkUnderilneOown]; 
ENDCASE « > [lfShift,ShiftUnderlineOown,UnderlineOown]; 

UNDERLINE Up ■ > SELECT ENABLE FROM 

Ievel4 a > [lfShift.ShiftUnderlineUp,UnderlineUp]; 
leveiS ■ > [lfShift,ShiftObkUnderiineUp,DbkUnderlmeUp]; 
ENDCASE a > [lfShift,ShiftUnderlmeUp,UnderlineUp]; 

-strikeout and supersub on daybreak only 
Strikeout Down ■ > [lfShift,ShiftStrlkeoutOown,StrlkeoutOown]; 
strikeout up * > [IfShift.ShiftStrikeoutUp.StrikeoutUp]; 
SuporSubDown ■ > [lfShift,ShiftSuperSubOown,SuperSubOown]; 
SuporSubup ■ > [lfShi'ft,ShiftSuperSubUp.SuperSubUp]; 

-superscript and subscript on dllon only 

SUPERSCRIPT Down ■ > (lfShift,ShiftSuperscriptOown,SuperscriptOown]; 
SUPERSCRIPT up ■ > [lfShift,ShiftSuperscrlptUp,SuperscriptUp]; 
SUBSCRIPT Down a > [lfShift,ShiftSubscnptOown,SubscnptOown]; 
SUBSCRIPT Up a > [lfShift,ShiftSubscriptUp,SubscriptUp]; 

SMALLER Down a > SELECT ENABLE FROM 

Ievel4 a > [lfShift,LargerOown,SnialterDown]; 

levels a > [lfShift,DbkLargerDown,DbkSmallerOown]; 

ENDCASE a > [lfShift,LargerOown,SmallerDown]; 
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SMALLER up ■ > SELECT ENABLE FROM 

Ievel4 ■ > [lfShift,LargerUp,SmailerUp]; 
levels « > [lfShift.DbkLargerUp,ObkSmailerUp]; 
ENOCASE ■ > [lfShift,LargerUp,SmallerUp]; 

-margins key is a softkey on daybreak and a right function key on diion 
MARGINS Down WHILE levels m > [lfShift«ShiftMarginsOown.MarginsDown]; 
MARGINS up WHILE levels ■ > [lfShift,ShiftMargmsUp,MarginsUp]; 

-defaults key on dlion only 

DEFAULTS Down m > [lfShift,ShiftOefaultsOown,DefaultsDown]; 
DEFAULTS Up ■ > [lfShift,ShiftDefaultsUp,OefaultsUp]; 

-font key is a softkey on daybreak and a right function key on dlion 
FONT Down WHILE levels a > [ifShlft,ShiftFontDown,FontDown]; 
FONT Up WHILE levels ■ > [lfShift,ShiftFontUp,FontUp]: 



ENOCASE... 
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A.4.2 Mouse Mode Tables 

The mouse mode tables refer to the set of tables that will be swapped in and out of the 
TIPStar watershed at the mouseActions placeholder, depending on the mode set in 
TiPStar.SetMode. TiPStar.Modesare normal, copy, move, and sameAs. 

Note: mode > normal will return NormalMouse.TIP to the watershed. 



"File: CopyModeMouse.TIP /asted/t: lO-Apr-a? 16:35:27 
OPTIONS Small: 
SELECT TRIGGER FROM 
MOUSE m > SELECT ENABLE FROM 

Point Down > > COORDS. CopyModeMotion,MouseLeft; 
Adjust Down > > COORDS, CopyModeMotion,MouseRight: 

ENDCASE: 

Point Down ■ > COORDS. CopyModeOown, KEY; 
Point Up » > COORDS. CopyModeUp, KEY; 
Adjust Down « > COORDS, Copy ModeOown, KEY: 
Adjust Up « > COORDS. CopyModeUp, KEY: 

ENTER a > Copy[\^odeEnter: 
EXIT M > CopyModeExit: 



ENDCASE.. 
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"File: MoveModeIV[ouse.TIP /ast ed/t: lO-Apr-S? 16:35:21 
OPTIONS Small; 
SELECT TIUGGER FROM 
MOUSE m > SELECT ENABLE FROM 

Point Down « > COORDS, Mov«ModeMotion,MouseLeft: 
Adjust Down - > COORDS. MoveModeMotion,MouseRight: 

ENDCASE; 

Point Down « > COORDS. MoveModeOOwn, KEY: 
Point Up » > COORDS, MoveModeUp, KEY; 
Adjust Down m > COORDS. MOveModeOOWn, KEY; 

Adjust Up > > COORDS. MoveModeUp, key; 

ENTER m > MoveModeEnter; 
EXIT - > MoveModeExit; 



ENDCASE.. 
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"File: SaineAsModeMouse.TIP /ast ed/ 1: IQ-Apr-Q? 16:35:58 
OPTIONS Small; 
SELECT TRIGGER FROM 
MOUSE m > SELECT ENABLE FROM 

Point Down * > COORDS. SameAsModeMotion^MouseLeft; 
Adfustoown M > COORDS, SameAsModeMotion,MouseRight; 

ENOCASE: 

Point Down m > COORDS. SameAsModeOown, key.* 
Point Up « > COORDS. SameAsModeUp, key,- 
Adjust Down m > COORDS. SameAsModeOown, key; 
Adjust up » > COORDS. SameAsiVlGdeUp, key; 

ENTER 9 > SameAsModeEnter; 
EXIT m > SameAsModeExit; 

ENDCASE^ 
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A.5 Usage/Examples 

A.S.1 Using NormaiSoftKeys.TIP when installing client softKeys 

— define the Atoms for my NotifyProc to use — 

centerDown, boldDown, italicsOown, underlineOown, superscriptDown, 
subscriptDown, smallerOown, defauitsOown ; AtomJKTOM ♦-Atom.null; 

init: PROCEDURE ■ 
BEGIN 

— initiaUze my Atoms — 
centerOown 4- Atom.MakeAtomCCenterOown'*]; 
boidDown 4-Atoiii.MakeAtomC''BoidDown''L]; 
italicsOown «- Atom.MakeAtomritaiicsOown''L]: 
underrmeOown4-Atom.MakeAtomrUnderiineOown'*L]; 
superscri ptDown Atom.MakeAtomrSuperscri ptDown"L]; 
subscri ptOown Atom. MakeAtomCSubscri ptDown'U; 
smailerDown4-Atom.MakeAtom("SmallerOown'*L]; 
END; "Init 

— somewhere in the code ~ 
softKeyHandle 4-SoftK«ys.Push{ 

notifyProc: MyNotifyProc, 

labels: 0ESCRiPT0R(labelSr SoftKeys-numberOf Keys] ]; 
MyNotifyProc: TiP.NottfyProc » 

BEGIN 

FOR input: TiP.Results results, input.next until input » nil oo 
WITH z: input select from 
atom ■ > select z.a from 
centerOown «> —Do something interesting—; 
boidDown »> —Do something interesting^-; 
italicsDown «> —Do something interesting— ; 
under! i neOown ^ > —Do something interesting— ; 
superscri ptOown »> —Do something interesting— ; 
subscriptDown ■ > —Do something interesting—; 
smallerOown m> — Do something interesting— ; 
defauitsOown « > —Do something interesting—; 

ENDCASE 
ENDCASE 
ENDLOOP 

END: — MyNotifyProc 



MyNotifyProc will be attached to NormaiSoftKeys.TIP by the SoftKeys implementation. 
Until this client does a SoftKeys.Remove, whenever the user presses one of the top row 
function keys MyNotifyProc will.be called with the appropriate production from the 
NormalSoftKeys.TIP. 
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A.5.2 Attaching a Notify Proc to One of the Normal Tables 

If a client application wants to grab the use, for example, of all the side keys for some 
period of time, it can attach a notifyProc to the NormaiSideK«ys.TIP table by calling: 

old 4- TiP.SetNotifyProcForTabietnpstar.GetTabie(sideKey$l. My Notify Proc]; 
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A.6 Index of TIP Tables 



Item 


Page 


CopyModeMouse.TIP 


16 


MoveModeMouse.TIP 


17 


NormalBackstop.TIP 


7 


Normal Key board.TIP 


8 


NormalMouse.TIP 


9 


NormalSideKeys.TlP 


11 


NormalSoftKeys.TIP 


14 


SameAsModeMouse.TIP 


18 
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References 

The following documents should be studied before or in conjunction with this manual: 

• Mesa Language Manual (Q10EQQ17Q). 

• XDE User Guide (610E0014Q). 

• Pilot Programmer's Manual ( 610E00160). 

• Srvices Programmer's Guide: Filing Programmer's Manutd T^OEOOISO). 

In addition, any other documentation accompanying a release of ViewPoint should be 
consulted before writing any programs. A list of this documentation can be found in the 
release message for each release. 
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C.l Overview 

Atoms (see the Atom interface) are used in several places in ViewPoint. This appendix 
contains a list of the strings that represent them. 

C.2 Atoms as TIP Results in the System TIP Tables 

Most of the right-hand sides (TIP results) of the productions in the system-provided TIP 
Tables (see Appendix A) contain atoms. 

AdjustDown 

AdjustMotion 

AdjustUp 

AgainDown 

AgainUp 

aLeveU 

aLeveiS 

Backspace 

BackWord 

BoldDown 

BoldUp 

Case Down 

CaseUp 

CenterDown 

CenterUp 

GlearDown 

ClearUp 

CopyDown 

CopyModeDown 

CopyModeEnter 

CopyModeExit 

CopyModeMotion 

CopyModeMouse 

CopyModeUp 

CopyUp 

cursorKeys 
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DbkLargerDown 

DbkLargerUp 

DbkSmallerOown 

DbkSmallerUp 

DbkUnderlineOown 

DbkUnderlineUp 

DefaultsDown 

DefaultsUp 

DefineOown 

DefineUp 

DeleteDown 

DeieteUp 

DiagnosticBitOne 

DiagnosticBitOneDown 

DiagnosticBitTwo 

DiagnosticBitTwoDown 

DwnArrowDown 

DwnArrowUp 

eL6vel4 

eLevelS 

EndDown 

EndPageDown 

EndPageUp 

EndUp 

Enter 

Exit 

ExpandDown 

ExpandUp 

FindDown 

FindUp 

FontDown 

FontUp 

HelpDown 

HelpUp 

HomeDown 

HomeUp 

ItalicsOown 

Italics Up 

jLevel4 

jLeveiS 

KeyboardDown 

KeyboardUp 

KeypadAdd 

KeypadClear 

KeypadComzna 

KeypadDivide 

KeypadEight 

KeypadFive 

KeypadFour 

KeypadMultiply 

KeypadNine 

KeypadOne 
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KeypadPeriod 

KeypadSeven 

KeypadSix 

KeypadSubtract 

KeypadThree 

KeypadTwo 

KeypadZero 

LargerDown 

LargerUp 

LeftArrowDovm 

LeftArrowUp 

LeflShiftAltOown 

level4 

levels 

LockDown 

LockUp 

MarginsDown 

MarginsUp 

MouseMiddleDown 

MouseMiddleMotion 

MouseMiddleUp 

MoveOown 

MoveModeDown 

MoveModeEnter 

MoveModeExit 

MoveModeMotion 

MoveModeMouse 

MoveModeUp 

NewLine 

NewParagraph 

NextDown 

NextPageOown 

NextPageUp 

NextUp 

NumLockKeyDown 

OpenDown 

OpenQuote 

OpenUp 

ParaTabDown 

PointDown 

PointMotion 

PointUp 

PrevPageDown 

PrevPageUp 

PropsDown 

PropsUp 

RightArrowDown 

RightArrowUp 

SameAsModeDown 

SameAsModeEnter 

SameAsModeExit 

SameAsModeMotion 
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SameAsModeMouse 

SameAsModeUp 

SameDown 

SamelJp 

ShiftAgainOown 

ShiftAgainUp 

ShiftCaseDown 

ShiftCaseUp 

ShiftCenterOown 

ShiflCenterUp 

ShiftClearOown 

ShiflClearUp 

ShiftCopyOown 

ShiflCopyUp 

ShiftDbkUnderlineDown 

ShiftObkUnderlineUp 

ShiftOefaultsDown 

ShiftDefaultsUp 

ShiftDeleteDown 

ShiftDeleteUp 

ShiftFindDown 

ShiftFindUp 

ShiftFontOown 

ShiflFontUp 

ShiftHelpDown 

ShiftHelpUp 

ShiftltalicsDown 

ShiftltalicsUp 

ShiftKeyboardDown 

ShiftKeyboardUp 

ShiftMarginsDown 

ShiEtMarginsUp 

ShiftMoveOown 

ShiftMoveUp 

ShiftOpenDown 

ShiftOpenUp 

ShiftPropsDown 

ShiftPropsUp 

ShiftSameDown 

ShiftSameUp 

ShiftStop 

ShiftStopUp 

ShiftStrikeoutDown 

ShiilStrikeoutUp 

ShiftSubscriptDown 

ShiftSubscriptUp 

ShiftSuperscriptOown 

ShiftSuperscriptUp 

ShiftSuperSub Down 

ShiftSuperSubUp 

ShiftUnderlineOown 

ShiftUnderlineUp 
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ShiftUndoDown 

ShiftUndoUp 

SkipOown 

SkipUp 

SmallerDown 

SmallerUp 

StartPageDown 

StartPageUp 

Stop 

StopUp 

Strikeout 

StrikeoutDown 

StrikeoutUp 

subscript 

SubscriptOown 

SubscriptUp 

SuperscriptDown 

SuperscriptUp 

SuperSubDown 

SuperSubUp 

TabDown 

UnboldDown 

UnboldUp 

UnderlineDown 

UnderlineUp 

UndoDown 

UndoUp 

UpArrowDown 

UpArrowUp 

C.3 Passed as the **Atoni'* Parameter to a Containee.GenericProc 

These atoms may be passed to a Contain««.GenericProc as the atom parameter, indicating 
what operation the GenericProc should perform: 

CanYouTakeSelection 

CanYouTakeSelectionBackground 

CanYouTakeSelectionAndFork 

FreeMenu 

Menu 

Open 

Props 

TakeSelection 

TakeSelectionAndFork 

TakeSelectionBackground 

TakeSelectionCopy 

TakeSelectionCopyAndFork 

TakeSe lectionCopy Background 
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C.4 Event Atoms 



Events are identlHed by atoms (see the Event interface). The following events are 
explained in further detail in the chapter indicated.- 

Event EventPata Chanter where discussed 



AboutLoading 


ApplicatlonFold«rExtra.EventData 


ApplicationFolder 


ApplicationLoaded 


ApplicationFoid«rExtra.EventOata 


ApplicationFolder 


AtomicProflleChange 


UPTAtomTkTOM* 


AtomicProfile 


AttemptingLogoff 


LPT spadaiLogon JVctiveQueueRequest 


Star Desktop 


AttemptingLogofnPailed 


NIL 


Star Desktop 


BlackKeysChange 


BfackK«ys.Keyboard 


BlackKeys 


Desktop WindowAvailable 


NIL 


Star Desktop 


LoadedAndAboutToStart 


ApplicationFoid«rExtra.EventOata 


ApplicationFolder 


LoadVetoed 


ApplicationFoiderExtra.EventData 


ApplicationFolder 


Newlcon 


NIL 


Star Desktop 


Newlmplementation 


LPTNSFilaType 


Containee 


Logoff 


NIL 


StarDesktop 


Logon 


NIL 


StarDesktop 


LogonCompleted 


NIL 


StarDesktop 


NewSystemFont 


SimpiaTaxtFontMappedFontHandle 


SimpleTextFont 


NewSystemFontHeight 


LPT CARDINAL 


SimpleTextDispiay 


PlainTextFileEdited 


LPT NSFii«.Ref erence 





♦LPT Stands for LONG POINTER TO 

**PlainTextFileEdited is notified bySimpleEditorlmpl when a plain text file is edited. 



AtomicProfile Atoms 

AtomicProfile is used to save various values globally. Values are saved with the following 
atoms. See the AtomicProfile Chapter for information on how to retrieve the associated 
value. 

Atom: FuUUserName - Associated Value: An xstring.Reader, the fully qualified user's 
name as entered by the user at logon. 
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The Atom interface allows any value to be associated with any pair of atoms (see 
Atofn.GetProp, Atom.Pair, etc.). 



Atom 

CurrentUser 



MultiNational 



Property atom 
ConversationHandle 

FileService 

FullUserName 

IdentityHandle 



NSName 

SimpleldentityHandle 

ExtendedLanguage 

Language 

PaperSizes 

PhysicalKeyboard 

SortOrder 

Units 



Value 

LONG POINTER TO CH.ConversationHandle 
created by Logon during user 
authentication. 

The NSFilcService for the user's home file 
service. 

This xstring.Reader is the fully qualified 
name of the logged on user. 

Auth.ldentityHandle for the currently 
logged on user. This is created at logon if 
the user enters a password; it can be used 
to access any Network Service. It is 
created with strong authentication. 

This is an NSName.Name for the fully 
qualified name of the logged on user 

Just like IdentityHandle above, but 
created with simple authentication. 

LONG POINTER TO BOOLEAN 

LPT MuMNationaLLanguage 

LPT MultiNationai.PageSizes 

LPT MultiNationaLPhysicai Keyboard 

LPT xstring.SortOrder 

LPT MultiNational.Unit 



These MultiNational values are obtained from the WorkstationProfile. They are 
intended to be used for customizing workstations for a particular country. 
MultiNational. mesa is a Friends interface. 
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This appendix lists all public items from the public interfaces, i.e., the files in- 
XStringPubiicdf and BWSPubiicdf . 

~ ApplicationFolder Atom AtomicProfile Attention BlackKeys BWSAttributeTypes 
BWSFileTypes BWSZone Catalog Containee ContainerCache ContainerCacheExtra 
ContainerSource ContainerW'mdow ContainerWindowextra ContainerWindowExtra2 
Context Cursor Display Event FileContainerShell FiieContainerSource 
FileContainerSourceExtra FileContainerSourceExtra2 FormWindow 
FormWindowMessageParse IdleControl KeyboardKey KeyboardWindow Level IVKeys 
MenuData MessageWindow OptionFile PopupMenu ProductFactoring 
'''^i^ ProductFactoringProducts ProductFactoringProductsExtras PropertySheet Prototype 

PrototypeExtra Selection SimpleTextDisplay SimpleTextEdit SimpleTextFont 
SimpleTextFontExtra SoftKeys StarDesktop StarWindowShell StarWindowShell Extra 
StarWindowShellExtra2 TIP TlPStar TIPX Undo UnitConversion Window XChar XCharSetO 
XCharSet164 XCharSet356 XCharSet357 XCharSet360 XCharSet361 XCharSet41 
XCharSet42 XCharSet43 XCharSet44 XCharSet45 XCharSet46 XCharSet47 XCharSets 
XComSoftMessage XFormat XLReal XMessage XString XTime XToken 

Abs: "XLReal" procedure [Number] returns [Numberj; 
accentedLatin: -XCharSet?^;- XCharSets.Sets s LOOPHOLE[241]; 
accuracy: -XL/?ea/- NATURAL s 13; 

Acquire: -Context- procedure [type: Type, window: Window. Handle] 
RETURNS [Data]; 

Action: -Conta/nerSoorce-- TYPE = {destroy, relist, sleep, waiceup}; 
Action: -Se/ect/o/T- TYPE = machine oependent{ 

clear, mark, unmark, delete, ciearlfHaslnsert, save, restore, firstFree, 

last(255)}; 

actionToWindow: -77P-- packed array KeyName of boolean; 
ActOn: -Conta/nerSoorce- ActOnProc; 
ActOn: ~5e/ectfon~ procedure [action: Action]; 
ActOnProc: -Conta/nerSoorce- type = procedure [ 

source: Handle, action: Action}; 
ActOnProc: -Se/ect/on- type = procedure [data: Manager Data, action: 
Action] 

""^-^ RETURNS [cleared: boolean 'false]; 
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Add: -PrototypeExtra- procedure [ 

file: NSFile. Handle, version: Prototype.Version, ' '1 

subtype: Prototype.Subtype '0, session: NSFile.Session *LOOPHOLE[0]]; 
Add: -XLReai- procedure [a: Number, b: Number] returns [Number]; 
AddCiientOef inedCharacter: -SimpieTextFont- procedure [ 

width: cardinal, height: cardinal, bitsPerUne: cardinal, bits: long pointer, 

offsetlntoBits: cardinal *01 returns [XStringXharacterJ; 
AddData: -Conta/nerCac/ie- type s record [ 

dientOata: long pointer, 

ciientOataCount: cardinal, 

ciientStrings: long descriptor for array cardinal of XString.ReaderBody]; 
AddOependencies: -Event- procedure [ 

agent: AgentProcedure, my Data: long pointer, 

events: long descriptor for array cardinal of EventType, 

remove: FreeOataProcedure ^nil] returns [dependency: Dependency]; 
AddDependency: -Event- procedure [ 

agent: AgentProcedure, myData: long pointer, event: EventType, 

remove: FreeOataProcedure 'nil] returns [dependency: Dependency]; 
Addltem: ~A/fenuOata- procedure [menu: MenuHandie, new: ItemHandie]; 
AddMenultem: -Attention- procedure [item: MenuData.ltemHandle]; 
AddPopupMenu: -StarWindowShell- procedure [ 

sws: Handle, menu: MenuOata.MenuHandle]; 
AddReferenceToDesktop: -StarDesktop- procedure [ 

reference: NSFile. Reference, place: Window.Place "nextPlaceJ; 
AddToSystemKeyboards: -/Ceyboarc//Cey- PROCEDURE [keyboard: 
BlackKeys-Keyboardl; 

AdjustProc: -StarWindowSheil- type = procedure [ 

sws: Handle, box: Window.Box, when: When]; 
AgentProcedure: -Event- type = procedure [ 

event: EventType, eventOata: long pointer, myOata: long pointer] 

RETURNS [remove: boolean "false, veto: boolean "false]; 
AllocateAndlnsert: -MessageWindow- procedure [ 

parent: Window. Handle, place: Window.Place *LOOPHOLE[01, 

dims: Window.Dims "LOOPHOLE(23417Bl, zone: uncounted zone "LOOPHOLE[0], 

lines: cardinal "lOj returns [Window.Handle]; 
AllocateCache: -ContainerCache- procedure returns [Handle]; 
AllocateMessages: -XMessage- procedure [ 

applicationName: long string, maxMessages: cardinal, clientData: ClientOata, 

proc: DestroyMsgsProc] returns [h: Handle]; 
Alphabetic: -XToken- FilterProcType; 
AlphaNumeric: -XToken- FilterProcType; 
Append: -XTime- procedure [ 

w: XString. Writer, time: System.GreenwichlVleanTime 'defaultTime, 

template: XString. Reader "dateAndTime, Itp: LTP "useSystem]; 
AppendChar: -XString- procedure [ 

to: Writer, c: Character, extra: cardinal "OJ; 
AppendExtensionlf Needed: -XString- procedure [to: Writer, extension: Reader] 

returns [didAppend: boolean]; 
Appendltem: -ContainerCache- procedure [cache: Handle, addData: AddData] 0^ 

returns [handle: ItemHandie]; 
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Appendltem: -Form IV/ndow- procedure [ 

window: Window.Handle, item: ItemKey, line: Line, preMargin: cardinal '0, 

tabStop: cardinal 'nextTabStop, repaint: boolean 'true]; 
AppendLine: -FormWindow— procedure [ 

window: Window.Handie, spaceAboveLine: cardinal '0] returns [line: Line]; 
AppendReader: -XString- procedure [ 

to: Writer, from: Reader, fromEndContext: Context "unknownContext, 

extra: cardinal *0I; 
AppendStream: -XString- procedure [ 

to: Writer, from: Stream.Handle, nBytes: cardinal, 

fromContext: Context "vanillaContext, extra: cardinal "0] 

RETURNS [bytesTransf erred: cardinal]; 
AppendSTRING: -rXString" procedure [ 

to: Writer, from: long string, homogeneous: boolean 'false, 

extra: cardinal '0]; 
ArabicFirstRightToLeftCharCode: -XC/)ar-Environment.Byte = 48; 
Arc: -Display- procedure [ 

window: Handle, place: Window.Piace, radius: integer, startSector: cardinal, 

stopSector: cardinal, start: Window.Piace, stop: Window.Piace, 

lineStyie: LineStyie 'nil, bounds: Window.BoxHandle *nil]; 
ArcCos: -XLReal- procedure [x: Number] returns [radians: Number]; 
ArcSin: -XLReai- procedure [x: Number] returns [radians: Number]; 
ArcTan: -XLReal- procedure [x: Number] returns [radians: Number]; 
ArrayHandle: -MenuData- type = long descriptor for array cardinal of 

ItemHandle; 

ArrowFfavor: StaiWmdowShell- type = {pageFwd, pageBwd, forward, backward}; 
ArrowScrol I Acti on : -StarW/ndowShey/— TYPE = {start, go, stop}; 
ArrowScrollProc: -StarWindowShell-vf?^ a procedure [ 

sws: Handle, vertical: boolean, flavor: ArrowFlavor, 

arrowScrollAction: ArrowScroi I Action *go]; 
atom: -Atom- type [1]; 
atom: -f/P-TYPE = Atom .atom; 
attemptingLogoff : -StarDesktop- Atom.ATOM; 
AttentionProc: -TlP-n?^ a procedure [window: Window.Handle]; 
AttributeFormatProc: -Fi7eConta/nerSource~TYPE = procedure [ 

containeelmpi: Containee.lmplementation, containeeOata: Contai nee. Data Handle, 

attr: NSFile.Attribute, displayString: XString. Writer]; 
BackScanClosure: -XStr/ng- type a record [ 

proc: BackScanProc, env: long pointer]; 
BackScanProc: -XString- type a procedure [ 

beforePos: cardinal, env: long pointer] 

RETURNS [pos: CARDINAL, context: Context]; 
backStoplnputFocus: -TIP- readonly Window.Handle; 
beforeltemZero: -Conta/nerSource- Item Index = 177776B; 
beforeLogonSession: -Catalog- NSFile.Session; 
BeginFill: -Contai nerCache- procedure [ 

cache: Handle, fillProc: FillProc, clients: long pointer, 

fork: BOOLEAN "true]; 
Bit: -leve/ZV/CeyS" TYPE a KeyStations.Bit; 
BitAddress: -Display- type = BitBlt.BitAddress; 
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BitAddressFromPlace: -Display- procedure [ 

base: BitAddress, x: natural, y: natural, raster: cardinal] 

RETURNS [BitAddress]; 
BitBltFlags: -Display- type s BitBltBitBltFlags; 
bitFiags: -Display- BitBitFlags; 
Bitmap: -Display- procedure [ 

window: Handle, box: Window.Box, address: BitAddress, 

bitmapBitWidth: cardinal, flags: BitBltFlags "paintFlags, 

bounds: Window.BoxHandle "nil]; 
Bitmap: -FormWindow- type a record [ 

height: CARDINAL, 

width: CARDINAL, 

bitsPerUne: cardinal, 
bits: Environment.BitAddress]; 
BitmapPlace: -Wmdow- procedure [window: Handle, place: Place 'LOOPHOLE[0]] 
returns [Place]; 

BitmapPlaceToWindowAndPlace: -Window- procedure [bitmapPlace: Place] 

returns [window: Handle, place: Place]; 
Bits: -XLReal- type = array [0..3] of cardinal; 
Black: -Display- procedure [ 

window: Handle, box: Window.Box, bounds: Window.BoxHandle 'nil]; 
BlackParaileiogram: -Display- procedure [ 

window: Handle, p: Parallelogram, dstFunc: DstFunc "null, 

bounds: Window.BoxHandle "nil]; 
Blanks; -XFormat- procedure [h: Handle "nil, n: cardinal " 1]; 
Block: -XFormat- procedure [h: Handle "nil, block: Environment. Block]; 
Block: -XString- procedure [r: Reader] 

returns [block: Environment.Block, context: Context]; 
BodyEnumProc: -StarWindowShell- type. = procedure [victim: Window. Handle] 

RETURNS [stop: BOOLEAN "FALSE]; 

Boolean: -XToken- procedure [h: Handle, signalOnError: boolean "true] 

RETURNS [true: boolean]; 
BooleanChangeProc: -FormWindow- type = procedure [ 
window: W'rndow.Handle, item: itemKey, cailedBecauseOf : ChangeReason, 
newValue: boolean]; 
BooleanFalseDefault: -PropertySheet-vfP^ » boolean "false; 
BooleanltemLabel: -Form Window- TYPE = record [ 
var: select type: BooleanltemLabelType from 
string a > [string: XString. ReaderBody], 
bitmap » > [bitmap: Bitmap], 
endcase]; 

BooleanltemLabelType: -Form W/ndow- TYPE » {string, bitmap}; 
Box: -KeyboardWindow- type s record [ 

place: Window.Place, width: integer, height: integer]; 
Box: -Window-Tfps s record [place: Place, dims: Dims]; 
BoxEnumProc: -Window- type = procedure [Handle, Box]; 
BoxesAreOisjoint: -Window- procedure [a: Box, b: Box] returns [boolean]; 
boxFlags: -Display- BitBltFlags; 
BoxHandle: -W/ndow-- type = long pointer TO Box; 
Brackets: -XToken- QuoteProcType; 

BreakCharOption: -XStr/ng- type = {ignore, appendToFront, leaveOnRest}; 
BreakTable: -XString- type = long pointer to BreakTableObject; 
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BreakTableObject: -XString- type = record [ 
otherSets: StopOrNot "stop, 
set: Envlronment.Byte '0, 

codes: packed array [0..255] of StopOrNot "ALL[not]]; 

Brick: -O/sp/ay- TYPE = long descriptor for array cardinal of cardinal; 

BufferProc: -SimpleTextDisplay- type « procedure [ 

result: Result, string: XString.Reader, address: Environment.BltAddress, 
dims: Window.Oims, bitsPerLine: cardinal] returns [continue: boolean]; 

Byte: -XStr/ng- TYPE = Environment.Byte; 

ByteLength: -XStringr- procedure [r: Reader] returns [cardinal]; 

Bytes: -XString- type a long pointer to ByteSequence; 

ByteSequence: -XString- type = record ( 

PACKED SEQUENCE COMPUTED CARDINAL OF Byte]; 

CacheFillStatus: ~Conta/nerCache~TYPE s { 

no, inProgress, inProgressPendingAbort, inProgressPendingJoin, yes, 

yesWith Error, spare}; 
CallBack: -HP- procedure [ 

window: Window.Handie, table: Table, notify: CailBackNotifyProc]; 
CallBackNotifyProc: -HP- type = procedure [ 

window: Window. Handle, results: Results] returns [done: boolean]; 
CancelPeriodtcNotify: "TIP- procedure [PeriodicNotify] 

RETURNS [null: PeriodicNotify]; 
CanYouConvert: Selection- procedure [ 

target: Target, enumeration: boolean 'false] returns [yes: boolean]; 
CanYouTake: -ContainerSourcer- CanYouTakeProc; 
CanYouTakeProc: -ContainerSource-- type = procedure [ 

source: Handle, selection: Selection.ConvertProc 'nil] 

returns [yes: boolean]; 
caretRate: -77P- Process, Ticks; 

CatalogProc: ~Cata/og~ TYPE = procedure [catalogType: NSFile.Type] 

returns [continue: boolean "true]; 
Changelnfo: -ContainerSourcer type s record [ 

var: select changeType: QiangeType from 
replace s > [item: Item Index], 

insert a > [insertlnfo: long descriptor for array cardinal of Editlnfo], 
delete a > [deletelnfo: Editlnfo], 

ail 3 > NULL, 

noChanges a > null, 
endcase]; 

ChangeProc: -Containee- type a procedure [ 

changeProcOata: long pointer, data: OataHandle 'nil, 

changedAttributes: NSFile.Selections "[xxxx], noChanges: boolean 'false]; 
ChangeProc: -Conta/nerSoorce- type a procedure [ 

ChangeProcOata: long pointer, changelnfo: Changelnfo]; 
ChangeReason: -PormW/ndow-TYPE a {user, client, restore}; 
ChangeScope: ~P/7eCof?tainef5ource~ procedure [ 

source: ContainerSource. Handle, newScope: NSFiie.Scope]; 
ChangeSizeProc: -SimpleTextEdit- type a procedure [ 

f: Field, oldHeight: integer, newHeight: integer, repaint: boolean]; 
ChangeType: —ContainerSource— type = { 

replace, insert, delete, all, noChanges}; 
Char: -XFormat- procedure [h: Handle "nil, char: XString.Character]; 
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Character: -XChar- type = word; 

Character: -XString- type = XChar. Character; ^ 
CharacterLength: -XString- procedure [r: Reader] returns [cardinal]; 
CharRep: -XChar- type = machine dependent record [ 

set(0:0..7): Environment. Byte, code(0:8..1S): EnvironmentByte]; 
CharTransiator: -77P-type = record [proc: KeyToCharProc, data: long pointer]; 
ChoiceChangeProc: -FormW/ndow-TYPe = procedure [ 

window: Window.Handle, item: ItemKey, cailedBecauseOf: ChangeReason, 

oldVaiue: Choicelndex, newValue: Choicelndexj; 
ChoiceHintsProc: -FormWindow- type a procedure [ 

window: Window.Handle, item: ItemKey] 

RETURNS ( 

hints: long descriptor for array cardinal of Choiceindex, 

freeHints: FreeCholceHintsProcl; 
Choicelndex: -FormWindow- type s cardinal [0..37777B1; 
Choiceltem: -Form kV/ndow— TYPE = record [ 
var: select type: Choiceltemlype from 

string a > [choiceNumber: Choicelndex, string: XString. ReaderBody], 

bitmap = > [choiceNumber: Choicelndex, bitmap: Bitmap], 

wrapindicator s > null, 

endcaseI; 

Choiceltems: -FormWindow- type a long descriptor for array Choicelndex of 
Choiceltem; 

Choiceltemlype: —form Window- TYPE s {string, bitmap, wrapindicator}; 
Circle: -Display- procedure ( . 

window: Handle, place: Window.Place, radius: integer, 

lineStyle: LineStyle "nil, bounds: Window.BoxHandle 'nil]; 
Clarity: -Window- TYPE = {isClear, isDirty}; 
Clear: -A ttent/on- procedure; 

Clear: -MessageWindow- procedure [window: Window. Handle]; 
Clear: -Selection- procedure [unmark: boolean 'true]; 
ClearlnputFocusOnMatch: -TIP- procedure [Window.Handle]; 
OearManager: -VP- procedure; 
OearOnMatch: ~5e/ect/on~ procedure [ 

pointer: ManagerData, unmark: boolean 'true]; 
ClearSticky: -Attention- procedure; 
ClearWriter: -XString- procedure [w: Writer]; 
clickTimeout: -TIP- System.Pulses; 
ClientData: -Xf orniat- type « long pointer; 
ClientData: -XA/fessage- type = long pointer; 

clientDirectory Words: -BWSAttributeTypes- NSFile.ExtendedAttributeType = 
10373B; 

clientFileWords: -ewSAttr/buterypes- NSFile.ExtendedAttributeType = 10372B; 

Clients: -ContainerCache- procedure [cache: Handle] 
returns [clients: long pointer]; 

clientSize: -AWSAttr/bufefypes- NSFile.ExtendedAttributeType = 10375B; 

clientStatus: -SWSAtfr/buterypes- NSFile.ExtendedAttributeType = 10374B; 

Code: -XChar- procedure [c: Character] returns [code: Environment.Byte]; 

CodesO: -XCharSetO- type = machine dependent{ 

null, tab(9), lineFeed, formFeed(12), newLine, esc(27), space(32), 
exciamationPoint, neutral OoubieQuote, numberSign, currency, percentSign, 
ampersand, apostrophe, openParenthesis, cioseParenthesis, asterisk, plus, 
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comma, minus, period, slash, digitO, digit 1, digit2, digits, digit4, digits, 
digit6, digit?, digits, digits, colon, semicolon, lessThan, equals, 
greaterlhan, questionMark, commerciaiAt, upperA, upperB, upperC, upperO, 
upperE, upperF, upperG, upperH, upperl, upperj, upperK, upperL, upperM, 
upperN, upperO, upperP, upperQ« upperR, upperS, upperT, upperU, upperV, 
gpperW, upperX, upperY, upperZ, openBracket, backslash, closeBracket, 
circumflex, iowBar, grave, lowerA, lowerB, lowerC lowerO, lowerE, lowerF, 
lowerG, lowerH, lowert, lowerj, lowerK, lowerL, lowerM, lowerN, lowerO, 
lowerP, lowerQ, lowerR, lowerS, lowerT, lowerU, lowerV, lowerW, lowerX, 
lowerY, lowerZ, openBrace, verticalBar, closeBrace, tilde, 
invertedExclamation(161), cent, poundSterling, dollar, yen, section(167), 
ieftSingleQuote(169K leftDoubleQuote, leftOoubleGuillemet, leftArrow, 
upArrow, rightArrow, downArrow, degree, plusOrMinus, superscript2, 
superscripts, multiply, micro, paragraph, centeredDot, divide, 

■ rightSingleQuote, rightDoubleQuote, rightOoubleGuillemet, oneQuarter, oneHalf, 
threeQuarters, invertedQuestionMark, graveAccent(19S), acuteAccent, ' 
circumflexAccent, tildeAccent, macronAccent, breveAccent, overOotAccent, 
dieresisAccent, overRingAccent(202), cedilla, underline, doubleAcuteAccent, 
ogonek, hachekAccent, horizontal Bar, superscripti, registered, copyright, 
trademark, musicNote, oneEighth(220), threeEighths, fiveEighths, sevenEighths, 
ohmSign, upperAEdigraph, upperOstroke, feminineSpanishOrdinal, upperHstroke, 
upperlJdiagraph(230), upperLdot, upperLstrpke, upperOsiash, upperOEdiagraph, 
masculineSpanishOrdinal, upperThorn, upperTstroke, upperEng, lowerNapostrophe, 
lowerKgreenlandiC, lowerAEdigraph, lowerOstroke, lowerEth, lowerHstroke, 
lowerldotless, lowerlJdiagraph, lowerLdot, lowerLstroke, iowerOslash, 
lowerOEdiagraph, lowerSzed, lowerThorn, lowerTstroke, lowerEng, escape}; 

Codes164: --XC/»ai5ef764-TYPE = machine dependent{ 

kabu(3S), maruA, marui, maruU, maruE, maruO. maruRo, maruHa, maruNi, maruHo, 
maruHe, maruTo, maruTi, maruRi, maruNu, reserved(255)}; 

CodesS56: -XCharSetSSS- type = machine depenoent{ 

thickSpace(33), fourEmSpace, hairSpace, punctuationSpace, decimal Pot nt(46), 
absoluteValue(t24K simiiarTo(126), escape(2S5)}; 

Codes357: ~XC/tai5et357- TYPE a machine oepenoent{ 

nonBreakingSpace{33h nonBreakingHyphen, discretionaryHyphen, enDash, emDash, 
figureDash, neutralQuote, loweredLeftOoubleQuote, germanRightDoubleQuote, 
gulllemetLeftQuote, guiliemetRtghtQuote, enQuad, emQuad, figureSpace, 
thinSpace, dagger, doubleOagger, bra, ket, rightPointinglndex, 
leftPointingindex, leftPerp, rightPerp, keft2Perp, right2Perp, 
leftWhiteLenticuiarBracket, HghtWhiteLenticularBracket, nwArrow, seArrow, 
neArrow, swArrow, careOf, perThousand, muchLessThan, muchGreaterThan, 
notLessThan, notGreaterlhan, divides, doesNotOivide, parallel, notParallel, 
isAMemberOf, isNotAMemberOf, suchThat, doubleBackArrow, doubieDoubleArrow, 
doubleRightArrow, reversibleReaction2, reversibleReactionl, doubleArrow, 
curlyArrow, containsi, containedini. Intersection, union, containsOrEquals, 
contained I nOrEquals, contains2, containedln2, neitherConatainsNorlsEqualTo, 
neitherContai nedlnMorisEqualTo, doesNotContai n, isNotContai ned In, 
checketBallotBox, nullSet, abstractPlus, abstractMinus, abstractTimes, 
abstractDivide, centeredBullet, centeredRing, plancksConstant, litre, not, 
borkenVerticalBar, angle, sphericalAngle, identifier, because, perpendicular, 
isProportionalTo, equivalent, equalByOefinition, questioned Equality, integral, 
contourlntegral, approximatelyEquall, isomorphic, approximatelyEqual2, 
summation, product, root, minusOrPlus, shade, cruzeiro(161), florin, francs. 
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pesetas, europeanCurrency, milreis, genericlnfinity, number, take, tel, yogh, 
compiexNumber, natural Number, realNumber, integer, leftCeiling, rightCeiling, 
leftFioor, rightFioor, therExists, forAII, and, or, qed, nabia, 
partialDerivative, ocrHook, ocrFork, ocrChair, alternatingCurrent, 
doubleLowBar, arc, romanNumerall, romanNumeraiii, romanNumerailll, 
romanNumeraiiV, romanNumeralV, romanNumeralVI, romanNumeraiVII, 
romanNumeralVIII, romanNumeraiiX, romanNumeralX, spades, hearts, diamonds, 
dubs, checkMark, xMark, circled 1, drcied2, drdedS, cirded4, circledS, 
drdedS, circled?, circledS, circled9, drdedIO, circledRightArrow, 
cirdedRlghtThenOownArrow, cirdedOownlhenLeftArrow, peaceSymbol, smileFace, 
poison, thick Vertical Line, thickHorizontalLine, thicklntersectingLines, 
thinVerticalLine, thinHorizontalLine, thinln:tersectingLines, sun, 
firstQuarterMbon, thirdQuarterMood, mercury, jupiter, saturn, uranus, neptune, 
piuto, aquarius, pisces, aries, taurus, gemini, cancer, leo, virgo, libra, 
scorpius, Sagittarius, Capricorn, telephone, oneThird, twoThirds, escape}; 

Codes360: -XCharSetSBO- typs s machine oepenoentC 

ligatureFF(33), ligatureFFI, ligatureFFL, ligatureFI, ligatureFL, ligatureFT, 
sigmaFinaI(126), verticalTabGraphic(184), tabGraphic, lineFeedGraphic, 
formFeedGraphic. carriageReturnGraphic, newLineGraphic, available276B, 
available277B, availabieSOOB, availableSOIB, pageFormatGraphic, 
startOfDocumentGraphic, stopGraphic, availableSOSB, available306B, 
available307B, avaiiable310B, available311B, blackRectGraphic, 
checkerBoardGraphic, ibmOup, available315B, ibmFm, paraTabGraphic(217), 
available332B, available333B, available334B, newParagraphGraphic, 
available336B, available337B, available340B, boxMT, boxNOT, boxEllipsis, 
boxRange, boxUpperX, boxUpperA, boxdigit9, boxUpperZ, boxAsterisk, 
availabie3S2B, available353B, boxPlus, boxMinus, boxPeriod, boxComma, 
field FormatGreek(246), fieldFormatRussian, fieldFormatHiragana, 
fieldFormatKatakana, field FormatKanji, fieldFormatlapanese, spaceGraphicdot, 
spaceGraphicb, escape(255)}; 

Codes361: ~XC/)arSet357- TYPE a MACHINE depenoent{ 

upperAgrave(33), upperAacute, upperAcircumfiex, upperAtilde, upperAmacron, 
upperAbrev, upperAumlaut, upperAring, upperAogonek, upperCacute, 
upperCcircumflex, upperChighOot, upperCcedilla, upperChachek, upperOhachek, 
upperEgrave, upperEacute, upperEcircumflex, upperEmacron, upperEhighOot, 
upperEumlaut, upperEogonek, upperEhachek, upperGcircumfiex(57), upperGbrev, 
upperGhighOot, upperGcediila, upperHcircumflex, upperlgrave, upperlacute, 
upperlcircumflex, upperltilde, upperlmacron, upperlhighOot, upperiumlaut, 
upperlogonek, upperJcircumflex, upperKcedilla, upperlacute, upperLcedilla, 
upperLhachek, upperNacute, upperNtilde, upperNcedilla, upperNhachek, 
upperOgrave, upperOacute, upperOcircumflex, upperOtiide, upperOmacron, 
upperOumlaut, upperOOoubleAcute, upperRacute, upperRogonek, upperRhachek, 
upperSacute, upperScircumflex, upperScedilia, upperShachek, upperTcedilla, 
upperThachek, upperUgrave, upperUacute, upperU circumflex, upperUtilde, 
upperUmacron, upperUbrev, upperUumlaut, upperllring, upperUDoubleAcute, 
upperUogonek, upperWcircumflex, upperYgrave, upperYacute, upperYcircumflex, 
upperYumlaut, upperZacute, upperZhighOot, upperZhachek, lowerAgrave(161), 
lowerAacute, lowerAcircumflex. lowerAtilde, lowerAmacron, lowerAbrev, 
lowerAumlaut, lowerAring, lowerAogonek, lowerCacute, lowerCcircumflex, 
lowerChighOot, lowerCcedilla, iowerChachek, lowerOhachek, lowerEgrave, 
lowerEacute, lowerEcircumflex, lowerEmacron, lowerEhighDot, lowerEumlaut, 
lowerEogonek, lowerEhachek, lowerGacute, lowerGcircumfiex, lowerGbrev, 
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lowerGhighDot, lowerHcircumflex(189), lowerlgrave, lowerlacute, 
^_ J lowerlcircumflex, lowerltilde, lowerlmacron, lowerlumlaut(196), lowerlogonek, 

lowerJcircumfiex, lowerKcedilla, iowerLacute, iowerLcedilia, lowerLhachek, 
lowerNacute, lowerNtilde, lowerNcediiia, iowerNhachek, lowerOgrave, 
lowerOacute, lowerOcircumflex, lowerOtilde, lowerOmacron, lowerOumiaut, 
lowerODoubieAcute, iowerRacute, lowerRogon«k, lowerRhachek, lowerSacute, 
lowerScircumfiex, lowerScediila, iowerShachek, lowerTcediila, lowerThachek, 
lowerllgrave, lowerUacute, lowerUcircumfiex, lowerUtilde, lowerUmacron, 
iowerUbrev, lowerUumiaut, towerUring« lowerUDoubieAcute, lowerUogonek, 
lowerWcircumflex, lowerYgrave, lowerYacute, lowerYcircumflex, lowerYumlaut, 
lowerZacute, lowerZhighOot, lowerZhachek, escape(255)}; 

Codes41: ~XC/jarSef4T-TYPE = machine oependentC 

kanjiSpace<33), japaneseComma, japanesePeriod, dakuonMark(43), handakuonMark, 
repeatHiragana(51), repeatHiraganaWithOakuon, repeatKatakana, 
repeatKatakanaWithOakuon, reduplicate, redupiicateAboveitem, repeatKanji, 
shime, kanjiZero, iongVowelBar, hyphen<62)« paraileiSign(66), 
threeOotLeader(68), twoOotLeader, leftBrokenBracket(76), rightSrokenSracket, 
leftJapaneseQuote(86}, rightiapaneseQuote, leftlapaneseOoubleQuote, 
rightlapaneseOoubieQuote, ieftSlackLenticularSracket, 
rightBiackLenticularSracket, notEquai(98), iessThanOrEquaiTo(IOI), 
greaterThanOrEqualTo, infinity, therefore, male, female, minutes(108), 
seconds, degreesCelsius, whiteStar(121), blackStar, whiteCircle, biackCircle, 
buiisEye, whiteOiamond, escape(255)}; 

Code$42: -XC/iarSet42~ TYPE 3 MACHINE oepenoent{ 

blackOiamond(33), whIteSquare, biackSquare, whiteUpTriangie, blackUpTriangie, 
whiteDownTriangle, blackDownTriangle,]isKome, jisPostOffice, escape(255)}; 

Codes43: -XCharSet43- type = machine dependent{ 

musical Flat( 172), soundRecordingCopyright(174), ayn(176), alifHamzah, 
lowerLeftQuote, musicalSharp(188), mjagkijZnak, tverdyjZnak, risingTone(192), 
umiaut(201), highCommaOffCentre(203), highlnvertedComma, horn(206), 
hookToTheLeft(210), circieBelow(212), halfCircleBelow, dotBelow, 
doubleOotBelow, doubleUnderline(217), africanVertlcalBar, circumflexUndermark, 
leftHalf Of Ugature(221 ), rightHalfOf Ligature, rightHalfOf OoubieTilda, 
escape(255)}; 

Codes44: ~XC/?ar5et44- type s machine oepenoent{ 

hirSmallA(33), hirA, hirSmalll, hirl, hirSmallU, hirU, hirSmallE, hirE, 
hirSmaiiO, hirO, hirKa, hirGa, hirKi, hirGi, hirKu, hirGu, hirKe, hirGe, 
hirKo, hirGo, hirSa, hirZa, hirSi, hirJi, hirSu, htrZu, hirSe, hirZe, hirSo, 
hirZo. hirTa, hirOa, hirTi, hirOi, hirSmalITu, hirTu, hirDu, hirTe, hirDe, 
hirTo, hirDo, hirNa, hirNi, hirNu, hirNe, hirNo, hirHa, hirBa, hirPa, hirHI, 
hirBi, hirPi, hirHu, hirBu, hirPu, hirHe, hirBe, hirPe, hirHo, hirBo, hirPo, 
hirMa, hirMi, hirMu, hirMe, hirMo, hirSmallYa, hirYa, hirSmallYu, hirYu, 
hirSmallYo, hirYo, hirRa, hirRI, hirRu, hirRe, hirRo, hirSmallWa, hirWa, 
hirWi, hirWe, hirWo, hirN, escape(255)}; 

Codes45: -XC/)arSet45~ TYPE a machine dependent{ 

katSmallA(33), katA, katSmalll, kati, katSmallU, katU, katSmallE, katE, 
katSmallO, katO, katKa, katGa, katKi, katGi, katKu, katGu, katKe, katGe, 
katKo, katGo, katSa, katZa, katSi, katli, katSu, katZu, katSe, katZe, katSo, 
katZo, katla, katOa, katli, katOi, katSmallTu, katlu, katDu, katle, katDe, 
katTo, katDo, katNa, katNi, katNu, katNe, katNo, katHa, katBa, katPa, katHi, 
katBI, katPi, katHu, katBu, katPu, katHe, katBe, katPe, katHo, katBo, katPo, 
katMa. katMi, katMu, katMe, katMo, katSmallYa, katYa, katSmailYu, katYu, 
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katSmallYo, katYo, katRa, katRi, katRu, katRe, katRo, katSmallWa, katWa, 
katWi, katWe, katWo, katN, katVu, katSmailKa, katSmaliKe, escape(255)}; 
Codes46: -XCharSet46- type s machine oepenoent{ 

smootheBreathing(37), roughBreathing, iotaScript, upperPrime(52), lowerPrime, 
raisedPeriod(59), upperAipha(65), upperSeta, upperGamma(68)c upperOeita, 
upperEpsiion, upperStigma, upperOigamma, upperZeta, upperEta, upperTheta, 
upperiota, upperKappa, upperLambda, upperMu, upperNu, upperXi, upperOmkron, 
upperPi, upperKoppa, upperRho, upperSigma, a127B, upperlau, upperlipsiion, 
upperPhi, upperKhi, upperPsi, upperOmega, upperSampi. lowerAlpha(97), 
lowerBeta, lowerBetaMiddleWord, lowerGamma, towerOeita, iowerEpsiion, 
lowerStigma, lowerOigamma, lowerZeta, lowerEta, iowerlheta, lowerlota, 
lowerKappa, lowerLambda, lowerMu, lowerNu, lowerXi, lowerOmicron, lowerPi, 
lowerKoppa, lowerRho, iowerSigma« lowerSigmaMiddleWord, lowerTau, 
lowerUpsilon, lowerPhi, lowerKhi, lowerPsi, lowerOmega, iowerSampi, 
escape(255)}; 
Codes47: "XCharSetA?" type = machine depenoent{ 

upperA(33), upperBe, upperVe, upperGe, upperOe, upperYe, upperYo, upperZhe, 
upperZe, upperl, upperlKratkoye, upperKa, upperEI, upperEm, upperEn, upperO, 
upperPe, upperEr, upperEs, upperTe, upperU, upperEf, upperXa, upperTse, 
upperOie, upperSha, upperShCha, upperTvyordiiZnak, upperYeri, 
upperMyaxkiiZnak, upperEOborotnoye, upperYu, upperYa, lowerA(81)«.iowerBe, 
lowerVe, lowerGe, lowerOe, lowerYe, lowerYo, lowerZhe, lowerZe, lowerl, 
lowerlKratkoye, lowerKa, lowerEi, iowerEm, iowerEn, lowerO, lowerPe, iowerEr, 
lowerEs, lowerTe, lowerU, lowerEf, lowerXa, lowerTse, lowerChe, iowerSha, 
towerShCha, lowerTvyordiiZnak, lowerYeri, lowerMyaxkiiZnak, IcwerEOborotnoye, 
iowerYu JowerYa, escape(255)}; 
ColumnContents: -F/VeConta/nerSoorce-- type = long descriptor for array 

cardinal of CoiumnContentslnfo; 
ColumnContentslnfo: -F/7eContamerSoorce~TYPE = record [ 
info: select type: ColumnType from 
attribute a > [ 

attr: NSFiie.AttributeType, 

f ormatProc: Attri buteFormatProc ' nil, 

needsOataHandle: boolean * false], 
extended Attribute s > [ 

extendedAttr: NSFiie.ExtendedAttributeType, 

f ormatProc: Attri buteFormatProc 'nil, 

needsOataHandle: boolean 'false], 
multipleAttributes = > [ 

attrs: NSFile.Seiections, 

formatProc: MultlAttributeFormatProc 'nil, 

needsOataHandfe: boolean 'false], 
endcaseJ; 

ColumnCount: -ContainerSource- ColumnCountProc; 
ColumnCountProc: -ContainerSource- type s procedure [source: Handle] 

returns [columns: cardinal]; 
ColumnHeaderlnfo: -ContainerWindow— type s record [ 

width: CARDINAL, wrap: boolean 'true, heading: XString.ReaderBody]; 
ColumnHeaders: -ContainerWindow- tvpb = long descriptor for array cardinal of 

Col u m n Headerl nf o ; 
ColumnType: -FileContainerSource- type = { 

attribute, extendedAttribute, multipleAttributes}; 
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CommandProc: -FormWindow— type = procedure ( 
^np/ window: WIndow.Handle, item: ItemKey, clientData: long pointer]; 

Compare: -XLReal- procedure [a: Number, b: Number] returns [Comparison]; 
Compare: -XString- procedure [ 

r1: Reader, r2: Reader, ignoreCase: boolean 'true, 

sortOrder: SortOrder 'standard] returns [Relation]; 
CompareStringsAndStems: -XString- procedure [ 

r1: Reader, r2: Reader, ignoreCase: boolean 'true, 

sortOrder: SortOrder 'standard] 

RETURNS [relation: Relation, equalStems: boolean]; 
Comparison: --XI/?ea/- TYPE = {less, equal, greater}; 

compatibility: -BWSAttnbuterypes-NSFile.ExtendedAttributeType s 10376B; 
Compose: -XMessage- procedure [ 

source: XStri ng. Reader, desti nation : XStri ng. Writer, args: Stri ngArray] ; 
ComposeOne: -XMessage- procedure [ 

source: XStri ng. Reader, destination: XStri ng. Writer, arg: XStri ng. Reader]; 
ComposeOneToFormatHandle: -XMessage- procedure ( 

source: XStri ng. Reader, destination: XFormat.Handle, arg: XStri ng. Reader); 
ComposeToFormatHandle: ^XMessage- procedure [ 

source: XStri ng. Reader, destination: XFormat. Handle, args: StringArrayj; 
ComputeEndContext: -XString- procedure [r: Reader] returns [c: Context]; 
ConfirmChoices: -Attention-- TYPE « record ( 

yes: XStri ng. Reader, no: XString.Reader]; 
Conic: -Display- procedure [ 

window: Handle, a: long integer, b: long integer, c: long integer, 

d: long integer, e: long integer, errorTerm: long integer, 

start: Window.Place, stop: Window.Place, errorRef: Window.Place. 

sharpCornered: boolean, unboundedStart: boolean, unboundedStop: boolean, 

lineStyle: LineStyle 'nil, bounds: Window.BoxHandle 'nil]; 
containedln: -SWSAttr/buterypes- NSFile.ExtendedAttributeType = 10400B; 
Context: -XString- type a machine dependent record [ 

suffixSize(0:0..6):(1..21, 

homogeneous(0:7..7): boolean, 

prefix(0:d..15): EnvironmentByte]; 
Conversionlnfo: -5e/ect/on-TYPE = record [ 

SELECT type: * from 

convert = > null, 

enumeration = > [proc: procedure [Value] returns [stop: boolean]], 
query a > [query: long descriptor for array cardinal of QueryElement], 
enocase]; 

Dummy: definitions = 

BEGIN 

Convert: Selection- procedure [ 

target: Target, zone: uncounted zone 'LOOPHOLE[0]] returns [value: Value]; 
Converter: -ProductFactoringProducts- Product = 7; 
Convertlnteger: -UnitConversion- procedure [ 

n: long integer, inputUnits: Units, outputUnits: Units] 
'•■.^^ returns [long integer]; 

Convertltem: -ContainerSource- Con vertltem Proc; 
ConvertltemProc: --ContainerSource- type = procedure [ 

source: Handle, itemlndex: Itemindex, n: cardinal 
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target: Selection. Target, zone: uncounted zone, 

info: Selection. Con version Info "xxx, changeProc: ChangeProc 'nil, 

changeProcOata: long pointer *nil] returns [value: Selection. Value]; 
ConvertNumber: Selection- procedure [target: Target] 

RETURNS [ok: BOOLEAN, number long unspecified]; 
ConvertProc: -Selection- type = procedure [ 

data: ManagerOata, target: Target, zone: uncounted zone. 

info: Conversioninfo *xxx] returns [value: Value]; 
ConvertReai: <-C/mtConvers/on- procedure ( 

n: XLReal.Number, inputUnits: Units, outputUnits: Units] 

RETURNS [XLReal.Number]; 
Copy: -Selection- procedure [v: ValueHandle, data: long pointer]; 
CopyMove: ~5e/ect/on— ValueCopyMoveProc; 
CopyOrMove: -Selection- type = {copy, move}; 
CopyReader: -XString- procedure [r: Reader, z: uncounted zone] 

RETURNS [new: Reader]; 
CopyToNewReaderBody: -XString- procedure [r: Reader, z: uncounted 

ZOME] 

RETURNS [ReaderBody]; 
CopyToNewWriterBody: -XString- procedure [ 

r: Reader, z: uncounted zone, endContext: Context "unknownContext, 

extra: cardinal '0] returns [w: WriterBody]; 
Cos: -XLReal- procedure [radians: Number] returns [cos: Number]; 
coversheetOn: -BWSAttributeTypes- NSFile.ExtendedAttributeType s 
10412B; 

CR: -XFomiat- procedure [h: Handle *nil, n: cardinal *11; 

Create: -Catalog- procedure [ 09^ 

name: XString. Reader, catalogType: NSFile.Type, 

session: NSFile.Session 'LOOPHOLE[0]] returns [catalog: 
NSFile.Reference]; 

Create: -ContainerWindow— procedure [ 
window: Window. Handle, source: ContainerSource.Handle, 
columnHeaders: ColumnHeaders, firstltem: ContainerSource. Item Index '0] 

RETURNS ( 

regularMenultems: MenuOata.ArrayHandle, 

topPusheeMenu Items: MenuOata.ArrayHandle]; 
Create: -ContainerWindowExtra- procedure [ 

window: Window. Handle, source: ContainerSource.Handle, 
columnHeaders: ContainerWindow.ColumnHeaders, 
firstltem: ContainerSource. Item Index *0, readonly: boolean "false] 
returns [ 

regularMenultems: MenuOata.ArrayHandle, 
topPusheeMenultems: MenuOata.ArrayHandle]; 
Create: -Context- procedure [ 

type: Type, data: Data, proc: OestroyProcType, window: Window.Handle]; 
Create: -FileContainerShell- procedure [ 

file: NSFile.Reference, columnHeaders: ContainerWindow.ColumnHeaders, 
columnContents: FileContainerSource.ColumnContents, 
regularMenultems: MenuData.ArrayHandle 'xxx, 

topPusheeMenultems: MenuData.ArrayHandle "xxx, scope: NSFile.Scope ' 

XXX, 

position: ContainerSource. Item Index '0, 

options: FileContainerSource.Options "LOOPHOLE[0]] 

returns [shell: StarWindowShel I. Handle]; 
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Create: -FileContainerSource- procedure [ 

file: NSFi I e. Reference, columns: ColumnContents, scope: NSFile.Scope "xxx, 
options: Options *LOOPHOLE[01] returns [source: ContainerSource-. Handle); 

Create: "FormWindow- procedure [ 
window: Window. Handle, makeltemsProc: MakeltemsProc, 
layoutProc: LayoutProc "nil, windowChangeProc: GlobaiChangeProc 'nil, 
minDimsChangeProc: MinDimsChangeProc "nil, 
zone: uncounted zone "LOOPHOL£[0]« clientOata: long pointer "nil]; 

Create: -MessageWindow- procedure [ 

window: Window.Handle, zone: uncounted zone 'LOOPHOLE[0]« 
lines: cardinal "10]; 

Create: -^ropertySheet- procedure [ 

formWindowltems: FormWIndow.MakeltemsProc, menultemProc: MenultemProc, 
size: Window.Oims, menuitems: Menultems "propertySheetOefauitMenu, 
title: XString. Reader "nil, piaceToOisplay: Window.Place "nullPlace, 
formWindowltemsLayout: FormWindow. LayoutProc "nil, 
windowAttachedTo: StarWindowSheli.Handle "LOOPHOLE[0], 
globalChangeProc: FormWindow.GlobalChangeProc "nil, display: boolean "true, 
clientData: long pointer "nil, afterTakenOownProc: MenultemProc "nil, 
zone: uncounted zone "LOOPHOLEEOJ] returns [shell: StarWindowSheli.Handle]; 

Create: -Prototype- procedure ( 

name: XString. Reader, type: NSFile.Type, version: Version, 

subtype: Subtype "0, size: long cardinal "0, isDirectory: boolean "false, 

session: NSFile.Session 'LOOPHOLE[b]] returns [prototype: NSFile.Handle]; 

Create: -StarWindowShell" procedure ( 

transitionProc: TransitionProc "nil, name: XString. Reader "nil, 

namePicture: XString.Character "0, host: Handle "LOOPHOLE(01, 

type: ShellType "regular, sleeps: boolean "false, 

considerShowingCoverSheet: boolean "true, 

currentlyShowingCoverSheet: boolean "false, 

pushersAreReadonly: boolean "false, readonly: boolean "false, 

scroll Data: Scroll Data "vanilfaScrollData, 

garbageCollectBodiesProc: procedure [Handle] "nil, 

isCloseLegalProc: IsQoseLegalProc "nil, bodyGravity: Window.Gravity "nw, 

zone: uncounted zone "LOOPHOLE[0]] returns [Handle]; 

Create: -Window- procedure [ 

display: DispiayProc, box: Box, parent: Handle "rootWindow, 

sibling: Handle "nil, child: Handle "nil, ciearingRequired: boolean "true, 

windowPane: boolean "false, under: boolean "false, cookie: boolean "false, 

color: BOOLEAN "FALSE, zone: uncounted zone "LOOPHOLE[0]] 

RETURNS [window: Handle]; 

CreateBody: -StarWindowShell- procedure [ 

sws: Handle, repaintProc: procedure [Window.Handle] "nil, 
bodyNotifyProc: TIP.NotlfyProc "nil, box: Window. Box "xxx] 
RETURNS [Window.Handle]; 

CreateCharTabie: -TIP- procedure [ 

z: UNCOUNTED ZONE "LOOPHOLE[0], buffered: boolean "true] 
RETURNS [table: Table]; 

CreateDesktop: -StarDes/ctop- procedure [name: XString. Reader] 
RETURNS [fh: NSFile.Handle]; 

CreateField: -S/mp/efextfd/t- procedure [ 

clientData: long pointer, context: FieldContext, dims: Window.Oims, 
initString: XString. Reader "nil, 

flushness: SimpleTextDisplay.Flushness "fromFlrstChar, 
streakSuccession: SimpleTextDisplay.StreakSuccession "fromFlrstChar, 
readonly: boolean "false, password: boolean "false. 
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fixedHeight: boolean "false, font: SimpleTextFont.MappedFontHandle "nil, ^gg^i^ 
backing Writer: XString. Writer "nil, 

SPECIALKeyboard: BlackKeys. Keyboard "nil] returns [f: Field]; 
OeateFieldContext: -SimpleTextEdit" procedure [ 

z: UNCOUNTED ZONE, window: Window. Handle, changeSizeProc: ChangeSizeProc] 

RETURNS [fc: FieidContext]; 
OeateFiie: -Catalog- procedure [ 

catalogType: NSFile.Type "10476B, name: XString. Reader, type: NSFile.Type, 

isDirectory: boolean 'false, size: long cardinal *0, 

session: NSFile.Session aOOPHOLE(0]] returns [file: NSFile.Handle]; 
Createltem: -MenuData- procedure [ 

zone: uncounted zone, name: XString.Reader, proc: MenuProc, 

ItemData: long unspecified "OJ returns [ItemHandle]; 
CreateLinked: -PropertySheet- procedure [ 

formWindowltems: FdrmWindow.MakeitemsProc, menultemProc: Menu Item Proc, 

size: WIndow.Dims, menultems: Menultems "propertySheetDefaultMenu, 

title: XString.Reader "nil, placeToOisplay: Window.Ptace "nuilPlace, 

formWindowltemsLayout: FormWindow.LayoutProc "nil, 

windowAttachedTo: StarWindowShell. Handle "LOOPHOLE[0], 

globalChangeProc: FormWindow.GlobalChangeProc "nil, display: boolean "true, 

linkWindowltems: FormWindow.MakeltemsProc, 

linkWindowltemsLayout: FormWindow.LayoutProc "nil, 

clientData: long pointer "nil, afterTakenDownProc: MenultemProc "nil, 

zone: uncounted zone "LOOPHOLE[0]] returns [shell: StarWindowShell. Handle]; 
OeateMenu: -MenuData- procedure [ 

zone: uncounted zone, title: ItemHandle, array: ArrayHandle, 

copyltemslntoMenusZone: boolean "false] returns [MenuHandle]; 
CreatePeriodlcNotify: -TIP- procedure [ 

window: Window.Handle "nil, results: Results, milliseconds: cardinal, 

notifyProc: NotifyProc "nil] returns [PeriodicNotify]; 
CreatePlaceHolderTable: -f/P- procedure (z: uncounted zone "LOOPHOLEIO]] 

RETURNS [table: Table]; 
CreateProcType: -Context- type s procedure returns [Data, Destroy ProcType]; 
CreateTable: -TIP- procedure [ 

file: XString.Reader, z: uncounted zone "LOOPHOLE[0], 

contents: XString.Reader "nil] returns [table: Table]; 
Current: -XTime- procedure returns [time: System.GreenwichMeanTime]; 
DashCnt: -Display- cardinal s 6; 

Data: -Conta/nee- type = record [reference: NSFile.Reference "xxx]; 

Data: -Context- type s long pointer; 

DataHandle: -Containee- type a long pointer to Data; 

Date: -XFormat- procedure [ 

h: Handle "nil, time: System.GreenwichMeanTime "LOOPHOLE[ 1760131 12006], 

format: DateFormat "dateAndTime]; 
dateAndTlme: -XTime- XString.Reader; 
DateCoiumn: -FileContainerSource- procedure 

RETURNS [multipleAttributes ColumnContentslnfo]; 
DateFormat: -Xfomiat- TYPE = {dateOnly,timeOnly,dateAndTime}; 
dateOnly: -X77me- XString.Reader; 

DaysOfWeek: -XComSoft/Vfessage- TYPE s Keys [monday..sunday]; 
Decase: -XChar- procedure [c: Character] returns [Character]; 

Decimal: -XFormat- procedure [h: Handle "nil, n: long integer]; _ 
Decimal: -XToken- procedure [h: Handle, signalOnError: boolean "true] 

returns [i: long integer]; 
Decimal Format: -XFormat- NumberFormat; - 
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Decompose: -XMessage- procedure [source: XString. Reader] 

RETURNS [args; StringArrayl; 
DefaultFileConvertProc: -Containee- Selection.ConvertProc; 
defauitGeometry: -KeyboardWindow— BlackKeys.GeometryTabie; 
DefaultLayout: -FormWindow- LayoutProc; 
defauitPicture: -KeyboardWindow— BlackKeys-Picture; 
DefaultPlctureProc: -KeyboaixJW'mdoW" BlackKeys-PictureProc; 
defaultTabStops: "FormWindow- TabStops; 
defaultTime: -XTime— System.GreenwichMeanTime; 
Defined: -Cursor— type s Type [biank..column]; 
OeieteAII: -l/ndo-PRoaouRE; 

OeieteAndShowNextPrevious: "ContainerWindoW'- procedure [ 

window: Window.Handle, item: ContainerSource.ltemlndex, direction: Direction]; 
DeleteAndShowNextPrevious: -'ContainerWindowExtra2- procedure [ 

window: Window. IHandle, item: ContainerSource.ltemindex, 

di recti on : Contai nerWindow. Di recti on] 

returns [newOpenSheil: StarWindowShell. Handle); 
Deleteitems: -ContainerSource- DeleteltemsProc; 
DeieteltemsProc: -ContainerSotirce- type s procedure [ 

source: Handle, itemlndex: Itemlndex, n: cardinal "1, 

changeProc: ChangeProc *nil, changeProcData: long pointer *nil]; 
OeieteNltems: -ContainerCache- procedure [ 

cache: Handle, item: cardinal, nitems: cardinal " 1 ]; 
Delimited: -XToken- FilterProcType; 
Dependency: -Event- type [2J; 

Dereference: -XString- procedure [r: Reader] returns [rb: ReaderBody];. 
DescribeOption: -ProductFactoring- procedure [ 

option: Option, desc: XString. Reader, 

prerequisite: Prerequisite " null Prerequisite]; 
DescribeProduct: -ProductFactoring- procedure [ 

product: Product, desc: XString.Reader]; 
DescribeReader: -XString- Courier. Description; 
DescribeReaderBody: -XString- Courier. Description; 
desktop: -ewSfi/efypes- NSFile.Type = 10400B; 
desktopCatatog: ~8W5F//erypes~ NSFile.Type = 10400B; 
DesktopProc: -tdleControl- type = procedure; 
desktopWindowAvai iable: -StarOesktop- Atom .atom ; 
DestallBody: -StarWmdowS/ie//- procedure [body: Window.Handle]; 
Destroy: -Conta/neiW/nc/ow— procedure [Window.Handle]; 
Destroy: -Context- procedure [type: Type, window: Window.Handle]; 
Destroy: -FormW/ndow- procedure [window: Window.Handle]; 
Destroy: -MessageW/ndow— procedure [Window.Handle]; 
Destroy: -StarWindowShell- procedure [sws: Handle]; 
DestroyAli: -Context- procedure [window: Window.Handle]; 
DestroyBody: -StarWindowShell- procedure [body: Window.Handle]; 
DestroyField: -SimpleTextEdit- procedure [f : Field]; 
DestroyFieidContext: -SimpleTextEdit- procedure [fc: FieldContext]; 
end. 



Destroyltem: -FormW/ndow- procedure [ 

window: Window.Handle, item: ItemKey, repaint: boolean "true]; 
Destroyltem: -MenuData- procedure [zone: uncounted zone, item: ItemHandle]; 
Destroyltems: -FormWindow- procedure [ 

window: Window.Handle, item: long descriptor for array cardinal op ItemKey, 

repaint: boolean 'true]; 
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DestroyMenu: -MenuData- procedure [zone: uncounted zone, menu: MenuHandle]; 

OestroyMessages: -XMessage- procedure [h: Handle]; 

OestroyMsgsProc: -XMessage- type = procedure [clientOata: ClientOata]; 

DestroyProcType: -Context- TYPE = procedure [Data, Window.Handle]; 

DestroyTabie: -TIP- procedure [long pointer to Table]; 

□Fonts: -ProductFactoringProducts- Product = 3; 

Difficulty: -Selection- type s {easy, moderate, hard, impossible}; 

Digit: -XLReal- type a [0..9]; 

Digits: -XLReai-VfP£ a packed array [0..121 of Digit; 

Dims: -Window- type = record (w: integer, h: integerI; 

Direction: -Contai*ne/W/ndow~ TYPE = {next, previous}; 

Discard: -Selection- procedure [saved: Saved, unmark: boolean 'true]; 

DispiayProc: -Window- TYPE s procedure [window: Handle]; 

Divide: -XLReal- procedure [a: Number, b: Number] returns [Number]; 

DoAnUndo: -Undo- procedure; 

DoAnUnundo: -Undo- procedure; 

DoneLookingAtTextltemValue: -FormWindow- procedure [ 

window: Window. Handle, item: Item Key]; 
DoneWithString: -AtomicProfile- procedure [string: XString. Reader]; 
dontTimeout: -Attention— Process.Ticks = 0; 
DoTheGreeterProc: -IdleControl- GreeterProc; 
Double: -XLReal- procedure [Number] returns [Number]; 
DownUp: -LeveZ/VKeys-TYPE a KeyStation$.DownUp; 
DownUp: -77P-TYPE a Level IVKeys. Down Up; 
DstFunc: -Oisp/ay- TYPE a BitBlt.DstFunc; 
E: -XLReal- procedure returns [Number]; 
Editlnfo: -ContainerSource- type a record ( 

afterltem: Itemindex, nitems: cardinal]; 
Ellipse: -Display- procedure [ 

window: Handle, center: Window.Place, xRadius: integer, yRadius: integer, 

tineStyle: LineStyle 'nil, bounds: Window.BoxHandle 'nil]; 
Empty: -XString- procedure [r: Reader] returns [boolean]; 
empty Context: -XString- Context; 
Enabled: -ProductFactor/ng- procedure [option: Option] 

returns [enabled: boolean]; 
EntireBox: -Window- procedure [Handle] returns [box: Box]; 
EntryEnumProc: -OptfonFiVe- TYPE a procedure [entry: XString. Reader] 

returns [stop: boolean 'false]; 
Enumerate: -Catalog- procedure [proc: CatalogProc]; 
Enumerate: -Selection- procedure [ 

proc: EnumerationProc, target: Target, data: RequestorData 'nil, 

zone: uncounted zone 'LOOPHOLE[01] returns [aborted: boolean]; 
EnumerateAllMenus: -StarWindowShellExtra- procedure [ 

swvs: StarWindowShell. Handle, proc: StarWindowShell.MenuEnumProc]; 
EnumerateDisplayed: -StarWindowShell- procedure [proc: ShellEnumProc] 

RETURNS [Handle " LOOPHOLE[01]; 
EnumerateDisplayedOfType: -StarWindowShell- procedure [ 

type: ShellType, proc: ShellEnumProc] returns [Handle 'LOOPHOLE[0]]; 
EnumerateEntries: -OptionFile- procedure [ 

section: XString. Reader, callBack: EntryEnumProc, 

file: NSFile. Reference 'xxx]; 
EnumeratelnvalidBoxes: -W/ndow- procedure [window: Handle, proc: BoxEnumProc]; 
EnumerateKey boards: -KeyboardKey- procedure [ 

class: KeyboardClass, enumProc: EnumerateProc]; 
EnumerateMyDisplayedParasites: -StarWindowShell- procedure [ 

sws: Handle, proc: ShellEnumProc] returns [Handle 'LOOPHOLE[0]]; 
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EnumeratePopupMenus: StarWindowShell- procedure [ 

sws: Handle, proc: MenuEnumProcJ; 
EnumerateProc: -KeyboardKey- type « procedure [ 

keyboard: BlackKeys. Keyboard, class: KeyboardClass] 

returns [stop: BOOLEAN >alse]; 
EnumerateSections: ~OptfonF//e~ procedure [ 

callBack: SectionEnumProc, file: NSFile. Reference "xxx]; 
EnumerateString: ~AtomicProff/e~ procedure [ 

atom: Atom.ATOM, proc: procedure [XString.Reader]]; 
EnumerateTree: -^Window- procedure ( 

root: Handle, proc: procedure [window: Handle]]; 
EnumerationProc: -Selection^ type « procedure [ 

element: Value, data: RequestorOata] returns [stop: boolean "palse); 
Equal: -XLReal- procedure [a: Number, b: Number] returns [boolean]; 
Equal: -XString- procedure (r1: Reader, r2: Reader] returns [boolean]; 
Equivalent: -XString- procedure [r1: Reader, r2: ReaderJ returns [boolean]; 
eraseFlags: -Display- BitBltFlags; 
Error: -Containee- error [ 

msg: XString.Reader "nil, error: error "nil, errorData: long pointer "nil]; 
Error: -ContainerSource— error [ 

code: ErrorCode, msg: XString.Reader "nil, error: error 'nil, 

errorOata: long pointer "nil]; 
Error: -ContainerWindow" error [code: ErrorCode]; 
Error: -Context- error [code: ErrorCode]; 
Error: -FonnWindow— error [code: ErrorCode]; 
Error: -KeyboardKey- error [code: ErrorCode]; 
Error: -OptionFile- error [code: ErrorCode]; 
Error: -Prodoctfactonng— error [type: ErrorType]; 
Error: -PropertySheet- error [code: ErrorCode]; 
Error: -Selection- error [code: ErrorCode]; 
Error: -SimpleTextEdit- error [type: ErrorType]; 
Error: -StarWindowShell- error [code: ErrorCode]; 
Error: -TIP- error [code: ErrorCode]; 
Error: -Window- error [code: ErrorCode]; 
Error: -XFormat" error [code: ErrorCode]; 
Error: -XLReal- error [code: ErrorCode]; 
Error: -XMessage- error [type: ErrorType]; 
Error: -XString- error [code: ErrorCode]; 
ErrorCode: -ContainerSource- type = machine depenoent{ 

invaiidParameters, accessError. fileError, noSuchltem, other, last(15)}; 
ErrorCode: -ContainerWindow- type s machine dependent{ 

notAContainerWindow, noSuchltem, last(7)}; 
ErrorCode: -Context-VfPE = {duplicateType, wIndowlsNIL, tooManyTypes, other}; 
ErrorCode: -FormWindow- type = machine dependent{ 

notAForm Window, wrongltemType, invalidChoiceNumber, noSuchLine, 

alreadyAForm Window, InvaiiditemKey, item NotOn Line, duplicateltemKey, 

incompatibleLayout, alreadyLaidOut, last(15)}; 
ErrorCode: -KeyboardKey- type = { 

alreadylnSystem Keyboards, notlnSystemKeyboards, insufficientSpace}; 
ErrorCode: -Opt/onFf/e- TYPE = { 

invalidParameters, inconsistentValue, notFound, syntaxError}; 
ErrorCode: -PropertySheet- type = {notAPropSheet}; 
ErrorCode: -Selection- type = { 

tooManyActions, tooMany Targets, invalidOperation, operationFaiied, didntAbort, 

didntClear}; 
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ErrorCode: StarWindowShell- type = { 

desktopNotUp, notASWS, notStarStyie, tooMany Windows}; 
ErrorCode: -f/P- type s {noSuchPerlodicNotlfier, other}; 
ErrorCode: -Window-- type = { 

iiiegalBitmap, illegalFioat, windowNotChiidOfParent, whosSlidingRoot, 

noSuchSibling, noUnderVariant, windowlnTree, sizingWithBitmapUnder, 

i i legalStack, i n vai id Parameters}; 
ErrorCode: -XFomiat- type » {InvalidFormat, niiOata}; 
ErrorCode: -Xl./?ea/- type =* { 

bug« divideSyZero, invalidOperation, notANumber, overflow, underflow, 

unimpiemented}; 
ErrorCode: -XString- type = { 

invalidOperation, multipieCharSets, tooManySytes, invalidParameter}; 
ErrorType: -ProductFactoring-- type = { 

dataNotFound, notStarted, illegaiProduct, illegalOption, missingProduct, 

missingOption}; 
ErrorType: -SimpleTextEdit- type = { 

fieidlsNoplace, noRoomlnWriter, lastCharGTfirstChar}; 
ErrorType: -XMessage- type = { 

arrayMismatch, InvalidMsgKeyList, invaiidStrihgArray, invaiidString, 

notEnoughArguments}; 
EventData: -ApplicationFolder- type = record [ 

applicatlonFoider: NSFi I e. Reference, internal Name: XString.Reader]; 
EventType: -£ver»t-TYPE = Atom.ATOM; 
Exp: -XlL/?ea/~ procedure [Number] returns [Number];. 
ExpandWriter: -XString- procedure (w: Writer, extra: cardinal]; 
Fetch: -Cursor- procedure [h: Handle]; 

FetchFromType: -Cursor— procedure [h: Handle, type: Defined]; 

Field: -S/mp/erextfd/t- type = long pointer to FieldObject; 

FieldContext: -SimpleTextEdit-TfPE = long pointer to FieldContextObject; 

FieldContextObject: -SirrtpleTextEdit- type; 

FieldObject: -SirrtpleTextEdit- type; 

fiftyPercent: -Display- Brick; 

filedrawerReference: -BWSAttributeTypes- NSFile.ExtendedAttributeType = 
10407B; 

FillProc: -ContainerCache- typb = procedure (cache: Handle] 

returns [errored: boolean * false]; 
FillResolveBuffer: -SimpleTextDisplay- procedure [ 

string: XString.Reader, lineWidth: cardinal "177777B, 

wordBreak: boolean 'TRUE,streakSuccession: StreakSuccession *fromFirstChar, 

resolve: ResolveBuffer, font: SimpleTextFont.MappedFontHandle "nil] 

returns [width: cardinal, result: Result, rest: XString.ReaderBody]; 
Filtered: -XToken- procedure [ 

h: Handle, data: FilterState, filter: FilterProcType, 

skip: SkipMode 'whiteSpace, temporary: boolean "true] 

RETURNS [value: XString.ReaderBody]; 
FilterProcType: -Xrofcen- type ^ procedure [ 

c: XChar. Character, data: FilterState] returns [inClass: boolean]; 
FilterState: -xro/f en- TYPE a long pointer to Standard FilterState; 
Find: -Context- procedure [type: Type, window: Window. Handle] returns [Data]; 
Find: -Prototype- procedure ( 

type: NSFile.Type, version: Version, subtype: Subtype '0, 

session: NSFile.Session *LOOPHOLE(0]] returns [reference: NSFile.Reference]; 
FindOescriptionFiie: -App//cat;onfo/der- procedure [ 

applicationFolder: NSFile.Handle] returns [descriptionFile: NSFiie.Referencej; 
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FindOrCreate: -Context- procedure [ 

type: Type, window: Window.Handle, createProc: CreateProcType] returns [Data]; 
First: -XString- procedure [r: Reader] returns [c: Character]; 
fi rstAvai lableAppI icationType: -BWSAtthbuteTypes- 

NSFile.ExtendedAttributelype = 10505B; 
firstBWSType: -awSAttributefypes- NSFiie.ExtendedAttributeType = 10400B; 
firstOldApplicationSpecific: "BWSAttributeTypes- 

NSFiie.ExtendedAttributeType 3 10414B; 
firstSpareBWSType: -eWSAttrfbutefypes- NSFiie.ExtendedAttributeType s 10461B; 
firstStarType: -AWSfi/efypes- NSFile.Type = 10400B; 
Fix: "XLReal- procedure [Number] returns [long integer]; 
FixdPtNum: -Display^ type » machine dependent record [ 

SELECT OVERLAID * from 

wholeThing = > [li(0:0..31): long integer], 

parts a > [frac(0:0..15): cardinal, int(1:0..15): integer], 

endcase]; 

Float: -Window- procedure [window: Handle, temp: Handle, proc: FloatProc]; 

Float: -XLReal- procedure [long integer] returns [Number]; 

FloatProc: -Window- type = procedure [window: Handle] 
returns [place: Place, done: boolean]; 

Flushness: -Fom? W/ncfow— type = SimpleTextDisplay.Flushness; 

Flushness: -^SimpleTextDisplay-VfPE = £flushLeft,flushRight, fromFlrstChar}; 

FlushUserinput: -TIP- procedure; 

FocusTakesinput: -TIP- procedure returns [boolean]; 

FontNotFound: -5/mp/erextFont- signal [name: XString. Reader]; 

Format: -XTime- procedure [ 

xfh: XFormat. Handle *nil, time: System.GreenwichMeanTime "defaultTime, 
template: XString.RiBader 'dateAndTime, Itp: LTP 'useSystem]; , 

formatHandle: -Attention— XFormat.Handle; 

FormatProc: -XFormat- type = procedure [r: XString. Reader, h: Handle]; 
FormatReai: -XLReal- procedure [ 

h: XFormat. Handle "nil, r: Number, width: natural]; 
FractionPart: -Xt/?ea/- procedure [Number] returns [Number]; 
Free: -Selection- procedure [v: ValueHandle]; 

Free: -W/ndow- procedure [window: Handle, zone: uncounted zone "LOOPHOLE[0]]; 
FreeBadPhosphorList: -W/ndow- procedure [window: Handle]; 
FreeCache: -ContainerCache-- procedure [Handle]; 
FreeChoiceHintsProc: -FormWindow- type = procedure [ 

window: Window. Handle, item: ItemKey, 

hints: long descriptor for array cardinal of Choicelndex]; 
FreeChoiceitems: -FormWindowMessageParse- procedure [ 

choiceltems: FormWindow.Choiceltems, zone: uncounted zone); 
FreeContext: -Selection- procedure [v: ValueHandle, zone: uncounted zone); 
FreeDataProcedure: -fvent- type = procedure [my Data: long pointer]; 
FreeMark: ~Co/ttamerCac/»e- procedure [mark: Mark]; 

FreeMsgOomainsStorage: -XMessage- procedure [msgOomains: MsgOomains]; 
FreeReaderBytes: -XStr/ng- procedure [r: Reader, z: uncounted zone]; 
FreeReaderHandte: -XToiicen- procedure [h: Handle] returns [nil: Handle]; 
FreeResolveBuffer: -S/mp/efextO/sp/ay- procedure [ResolveBuffer]; 
FreeStd: -Selection- ValueFreeProc; 

FreeStreamHandte: -XTo/iren- procedure [h: Handle] returns [s: Stream. Handle]; 
FreeTextHintsProc: -FormWindow- type = procedure [ 
window: Window. Handle, item: ItemKey, 

hints: long descriptor for array cardinal of XString. ReaderBody]; 
FreeTokenString: -XToken- procedure [r: XString. Reader] 
RETURNS [nil: XString.Reader 'nil]; 
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FreeTree: -Window- procedure [ 

window: Handle, zone: uncounted zone *LOOPHOLE[0]]; 
FreeWriterBytes: -XString- procedure [w: Writer]; 
FromBiock: -XString- procedure ( 

block: Environment.Block, context: Context "vaniliaContext] 

RETURNS [ReaderBodyl; 
FromChar: -XString- procedure [char: long pointer to Character] 

RETURNS [ReaderBody]; 
FromName: ~iApp//cat/onfo/der- procedure [internal Name: XString. Reader] 

RETURNS [appiicationFolder: NSFtie.Reference]; 
FfomNSString: -XString^ procedure [ 

$: NSString.String, homogeneous: boolean "false] returns [ReaderBody]; 
FfomSTRING: -XStr/ng- PROCEDURE [s: long string, homogeneous: boolean >alse] 

returns [ReaderBody]; 
fuHUserName: StarDesktop- Atom.ATOM; 
GenericProc: -Containee- type a procedure [ 

atom: Atom.ATOM, data: OataHandle, changeProc: ChangeProc 'nil, 

changeProcOata: long pointer "nil] returns [long unspecified]; 
GeometryTable: -BlackKeys- type s long pointer; 
Geometry TableEntry: -KeyboardWindow- type s record [ 

box: Box, key: Keystations, shift: ShiftState]; 
Get: -XMessage- PROCEDURE [h: Handle, msgKey: MsgKey] 

RETURNS [msg: XString. ReaderBody]; 
GetAdjustProc: -rStarWmdowS/ie//- procedure [sws: Handle] returns [AdjustProc]; 
GetAvailableBodyWindowOims: -StarWindowShell- procedure [sws: Handle] 

RETURNS [Window. Dims]; 
GetBitmapUnder: -Window- procedure [window: Handle] returns [long pointer]; 
GetBody: -5ta/W/ndow5/)e//~ procedure [sws: Handle] returns [Window.Handie]; 
GetBodyWindowJustFits: StarWindowShell- procedure [sws: Handle] 

returns [boolean]; 

GetBOOLEAN: -AtomicProfile- procedure [atom: Atom.ATOM] returns [boolean]; 
GetBooleanitemValue: -FormWindow- procedure [ 

window: Window.Handie, item: ItemKey] returns [value: boolean]; 
GetBooleanValue: -OptionFile- procedure [ 

section: XString. Reader, entry: XString.Reader, file: NSFile.Reference 'xxx] 

RETURNS [value: boolean]; 
GetBox: SimpleTextEdit- procedure [f: Field] returns [box: Window.Box]; 
GetBox: -Window- procedure [Handle] returns [box: Box]; 
GetCachedName: -Containee- procedure [data: OataHandle] 

RETURNS [name: XString. ReaderBody, ticket: Ticket]; 
GetCachedType: -Containee- procedure [data: OataHandle] 

RETURNS [type: NSFile.Type]; 
GetCaretPlace: -SimpleTextEdit- procedure [context: FieldContext] 

RETURNS [place: Window.Piace]; 
GetCharProcType: -Xro/fen- type = procedure [h: Handle] 

RETURNS [c: XChar.Character]; 
GetCharTranslator: -TIP- procedure [table: Table] returns [o: CharTranslator]; 
GetCharWidth: -SimpierextDisplay- procedure [ 

char: XChar.Character, font: SimpleTextFont.MappedFontHandle "nil] 

returns [width: cardinal]; 
GeKhild: ~W/ndow- procedure [Handle] returns [Handle]; 
GetChoiceitem Value: -FormWindow- procedure [ 

window: Window.Handie, item: ItemKey] returns [value: Choicelndex]; 
GetClearingRequired: -Window- procedure [Handle] returns [boolean]; 
GetClientOata: -FormWindow- procedure [window: Window.Handie] 

RETURNS [ciientData: long pointer]; 
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GetClientOata: -SimpleTextEdit-- procedure [f: Field] 

RETURNS [clientOata: long pointer]; 
GeKontainee: -StarWindowSheil- procedure [sws: Handle] 

RETURNS [Contai nee. Data J; 
GetdntainerSource: -FileContainerSheH- procedure [ 

shell: StarWindowSheli.Handle] returns [source: Contai nerSource. Handle]; 
GetG>ntainerWindow: -FUeContainerSheil-' procedure [ 

shell: StarWindowShell.Handiel returns [window: Window. Handle]; 
GetCurrentDesktopFile: StarDesktop- procedure returns [NSFile. Reference]; 
GetCurrentKeyboard: -BtackKeys- procedure returns [current: Keyboard]; 
GetOecimalltemVaiue: -FQimWindow" procedure [ 

window: Window.Handie, item: ItemKey] returns [value: XLReal. Number]; 
GetOefauitlmpiementation: -Containee- procedure returns [Implementation]; 
GetOesktopProc: -IdleControt- procedure [atom: Atom.ATOM] 

returns [DesktopProc]; 
GetOims: -Window- procedure [Handle] returns [dims: Dims); 
GetDisplayProc: -Window- procedure [Handle] returns [DisplayProc]; 
GetDisplayWindow: -KeyboardWindow- procedure returns [Window. Handle]; 
GetFteldContext: ~5/mp/e7ext£d/t~ procedure [f: Field] returns [FieldContext]; 
GetFile: -Catalog- procedure [ 

catalogType: NSFtie.Type * 10476B, name: XString. Reader, 

readonly: boolean 'false, session: NSFile.Session 'LOOPHOLE[0]] 

RETURNS [file: NSFile.Handle]; 
GetFlushness: -FormWindow- procedure [window: Window. Handle, item: ItemKey] 

RETURNS [old: Flushness]; 
GetFlushness: -SimpleTextEdit- procedure [f : Field] 

RETURNS [SimpleTextDisplay.Flushness]; 
GetFont: -SimpleTextEdit- procedure [f: Field] 

RETURNS [SimpleTextFont.MappedFontHandle]; 
GetFormWindows: -PropertyS/ieet- procedure [shell: StarWindowSheli.Handle] 

RETURNS [form: Window. Handle, link: Window.Handle]; 
GetGlobalChangeProc: -FormWindow- procedure [window: Window.Handle] 

RETURNS [proc: GlobalChangeProc]; 
GetGreeterProc: -IdleControl- procedure returns [GreeterProc]; 
GetHandle: -XComSoftMessage- procedure returns [h: XMessage.Handle]; 
GetHost: -StarWindowSheil- procedure [sws: Handle] returns [Handle]; 
Getlmpiementatlon: -Containee- procedure [NSFile.Type] 

RETURNS [Implementation]; 
Getlmplementation: -(/ncfo- procedure returns [Implementation]; 
Getlnfo: -Cursor- procedure returns [Info: Info]; 

GetlnputFocus: -5/mp/erext£d/t- procedure [fc: FieldContext] returns [Field]; 
GetlnputFocus: -TIP- procedure returns [Window.Handle]; 
GetlntegerttemValue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey] returns [value: long integer]; 
GetlntegerValue: -OptionFile- procedure [ 

section: XString. Reader, entry: XString. Reader, index: cardinal '0, 

file: NSFile. Reference *xxx] returns [value: long integer]; 
GetlsCloseLegalProc: -StarWindowSheil- procedure [sws: Handle] 

RETURNS [IsCloseLegalProc]; 
Getltemlnfo: -FileContainerSource- procedure [ 

source: ContainerSource.Handle, itemindex: ContainerSource.ltemlndex] 

returns (file: NSFile. Reference, type: NSFile.Type]; 
GetloinDirection: -XChar- procedure [Character] returns [JoinDirection]; 
GetLength: -Conta/nerCachefxtra- procedure [cache: Contai nerCache. Handle] 

RETURNS [cacheLength: cardinal]; 
GetLength: -ContainerSource- GetLengthProc; 
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GetLengthProc: -ContainerSource- type = procedure [source: Handle] 

RETURNS [length: gxroinal. totalOrPartial: Total OrPartiai 'total]; 
GetLimitProc: -StarW/ndowS/ie//- procedure [sws: Handle] returns [LimitProc]; 
GetLlst: -XMessage- procedure [ 

h: Handle, msgKeys: MsgKeyList, msgs: StringArray]; 
GetLONGlNTEGER: -AtomicProfile- procedure [atom: Atom.ATOM] 

returns [long integer]; 
GetManager: -HP-- procedure returns [current: Manager]; 
GetMode: -TiPStar- procedure returns [mode: Mode]; 
GetMultipieChoiceitemValue: -FormWindoW" procedure [ 

window: Window. Handle, item: ItemKey, zone: uncounted zone] 

returns [value: long descriptor for array cardinal of Cholcelndex]; 
GetNextAvaiiabieKey: ~FormlV/ndow~ procedure [window: Window.Handle] 

RETURNS [key: ItemKey]; 
GetNextOutOfProc: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey] returns [NextOutOfProcj; 
GetNextUnobscuredBox: -StarOesitrtop-- procedure [height: integer] 

RETURNS [Window. Box]; 
GetNotifyProc: -f/P- procedure [window: Window.Handle] returns [NotifyProc]; 
GetNotifyProcFromTabie: ~77P~ procedure [table: Table] returns [NotifyProc]; 
GetNthitem: -ContamerCac/ie- PROCEDURE [cache: Handle, n: cardinal] 

RETURNS [ItemHandie]; 
GetOpenitem: -ContainerWindow" procedure [window: Window.Handle] 

RETURNS [item: Contai nerSource. Item Index "177777B]; 
GetPane: -Window-- procedure [Handle] returns [boolean]; 
GetParent: -W/ndow- procedure [Handle] returns [Handle]; 
GetPlace: -TIP- procedure [window: Window.Handle] returns [Window.Place]; 
GetPlaceFromRef erence: -StarDesktop- procedure [ref : NSFi le. Reference] 

RETURNS [Window.Place]; 
GetPName: -Atom- procedure (atom: atom] returns [pName: XString. Reader]; 
GetProp: -Atom- procedure [onto: atom, prop: atom] returns [pair: RefPairj; 
GetPusheeCommands: -StarWindowShell- procedure [sws: Handle] 

RETURNS [ 

bottom: MenuOata.MenuHandie, middle: MenuOata.MenuHandle, 

top: MenuOata.MenuHandie]; 
GetReadOnly: -Form Window- procedure [window: Window.Handle, item: ItemKey] 

RETURNS [readonly: boolean]; 
GetReadOnly: -SimpleTextEdit- procedure [f : Field] 

RETURNS [readonly: boolean]; 
GetReadOnly: -StarW/ndowS^e//- procedure [sws: Handle] returns [boolean]; 
GetRegularCommands: -StarW/ndowShe//- procedure [sws: Handle] 

RETURNS [MenuOata.MenuHandie]; 
GetResuits: -TIPX- procedure [ 

window: Window.Handle, resultsWanted: ResultsWanted 'nil] 

RETURNS [results: TIP.Results); 
GetScroUData: "StarWindowShell" PROCEDURE [sws: Handle] 

RETURNS [scrollData: ScrollData] 
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GetSelection: -ContamerW/ndow— procedure [window: Window. Handle] 

RETURNS [ 

first: ContainerSource. Item Index, lastPlusOne: ContainerSource. Item Index]; 
GetShellFromReference: -StarOesilrtop- procedure [ref: NSFile.Reference] 

RETURNS [sws: StarWindowSheil.Handle]; 
GetShowKeyboardProc: -KeyboardKey- procedure returns [ShowKeyboardProc]; 
GetSibiing: "Window- procedure [Handle] returns [Handle]; 
GetSfeeps: StarWindowSheil- procedure [sws: Handle] returns [boolean]; 
GetSource: -ContainerW/ndow— procedure [window: Window. Handle] 

returns [source: ContainerSource.Handle]; 
GetState: StarWindowShen- procedure [sws: Handle] returns [State]; 
GetStreakNature: -XOiar- procedure [Character] returns [StreakNature]; 
GetStreakSuccession: -Form lV/ndow~ procedure [ 

window: Window. Handle, item: ItemKey] returns [old: StreakSuccession]; 
GetStreakSuccession: -S/mp/efextEd/t- procedure [f: Field] 

RETURNS [SimpieTextOisplay.StreakSuccession]; 
GetString: -AtomicProfUe- procedure [atom: Atom. atom] 

RETURNS [XString. Reader]; 
GetStringValue: -OptionFUe- procedure [ 

section: XString. Reader, entry: XString. Reader, 

callBack: procedure [value: XString. Reader], index: cardinal "0, 

file: NSFile.Reference 'xxx]; 
GetTable: -TIP- procedure [window: Window.Handle] returns [Table]; 
GetTable: -TIPStar- procedure [Placeholder] returns [TIP.Table]; 
GetTabieLink: -TIP- procedure [from: Table] returns [to: Table]; 
GetlableOpactty: -TIP- procedure [table: Table] returns [boolean]; 
GetTabStops: -FormWindow- procedure [window: Window.Handle] 
^^m^ RETURNS itabStops: TabStops]; 

GetTag: -form W/ndow— procedure [window: Window.Handle, item: ItemKey] 

RETURNS [tag: XString. ReaderBody]; 
GetTextltemValue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, zone: uncounted zone] 

RETURNS [value: XString. ReaderBody]; 
GetTransitlonProc: -StarWindowShell- procedure [sws: Handle] 

RETURNS [TransitionProcJ; 
GetType: ~5ta/W/ndow5he//~ procedure [sws: Handle] returns [ShellType]; 
GetUseBadPhosphor: -Window- procedure [Handle] returns [boolean]; 
GetUserProflle: -OptionFile- procedure returns [file: NSFile.Reference]; 
GetVaiue: -5/mp/e7ext£d/t~ procedure [f: Field] returns [XString.ReaderBody]; 
GetVlsibility: -Form W/ndow~ procedure [window: Window.Handle, item: ItemKey] 

RETURNS [visibility: Visibility]; 
GetWindow: -SimpleTextEdit- procedure [fc: FieldContext] 

RETURNS [window: Window.Handle]; 
GetWindow: -StarDesktop- procedure returns [Window.Handle]; 
GetWindowltemValue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey] returns [value: Window.Handle]; 
GetWorkstationProfile: -OptionFile- procedure 

returns [file: NSFile.Reference]; 
GetZone: -FormWindow- procedure [window: Window.Handle] 

returns [zone: uncounted zone]; 
GetZone: -SimpleTextEdit- procedure [fc: FieldContext] 

RETURNS [uncounted ZONE]; 

GetZone: -StarWindowShell- procedure [sws: Handle] returns [uncounted zone]; 
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GlobalChangeProc: -formW/ndow-TYPE = procedure! ^jH^ 

window: Window.Handle, item: ItemKey, calledBecauseOf: ChangeReason, 

clientOata: long pointer]; 
Gravity: -Window- type = {nil, nw, n, ne, e, se, s, sw, w, c, xxx}; 
Gray: -Display- procedure [ 

window: Handle, box: Window. Box, gray: Brick * fifty Percent, 

dstFunc: DstFunc 'null, bounds: Window.BoxHandle 'nil]; 
GrayTrapezoid: -Display- procedure [ 

window: Handle, t: Trapezoid, gray: Brick 'fiftyPercent, 

dstFunc: DstFunc 'null, bounds: Window.BoxHandle 'nil]; 
Greater: -XlReal- procedure [a: Number, b: Number] returns [boolean]; 
GreaterEq: -XLReal- procedure (a: Number, b: Number] returns [boolean]; 
GreeterProc: -IdleControl- type = procedure returns [Atom.ATOM]; 
Half: -XI/?ea/- procedure [Number] returns [Number]; 
Handle: -ContainerCache- type = long pointer to Object; 
Handle: -ContainerSource- type = long pointer to Procedures; 
Handle: -Cursor- TYPE a long pointer to Object; 
Handle: -Disp/ay- TYPE = Window.Handle; 
Handle: -StarWindowSheH-TfPE = record [Window.Handle]; 
Handle: -Window- type s long pointer to Object; 
Handle: -XFormat- type = long pointer to Object; 
Handle: -XMessage- type = long pointer to Object; 
Handle: -XToken- type s long pointer to Object; 

HasAnyBeenChanged: -FormWindow— procedure [window: Window.Handle] 

returns [yes: boolean]; 
HasBeenChanged: -FormWWndow— procedure [window: Window.Handle, item: ItemKey] 

RETURNS [yes: boolean]; i^H^ 
HaveOisplayedParasite: -StarWindowShell— procedure [sws: Handle] 

RETURNS [boolean]; 

Hex: -XFormat- procedure [h: Handle "nil, n: long cardinal]; 
HexFormat: -XFormat- NumberFormat; 
HighiightThisKey: -SoftKeys- procedure [ 

window: Window.Handle, key: cardinal "nullKey]; 
HostNumber: -XFormat- procedure [ 

h: Handle 'nil, hostNumber: System.HostNumber, format: NetFormat]; 
HowHard: ~5e/ect/on- procedure [target: Target, enumeration: boolean 'false] 

RETURNS [difficulty: Difficulty]; 
IconColumn: -FileContainerSource- procedure 

RETURNS [attribute ColumnContentslnfo]; 
Idle: -IdleControl- procedure; 

ignoreType: -Containee- NSFile.Type = 37777777777B; 
Implementation: -Contamee- TYPE s record [ 

implementors: long pointer "nil, 

name: XString.ReaderBody 'xxx, 

smallPictureProc: SmallPictureProc 'nil, 

pictureProc: PictureProc "nil, 

convertProc: Selection.ConvertProc "nil, 

genericProc: GenericProc 'nil]; 
Implementation: -Undo-v/PE = record [ 

opportunity: Proc, 

roadblock: procedure [XString. Reader], 
doAnUndo: procedure, 
doAnUnundo: procedure, 
deleteAII: procedure]; 
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IndexFromMark: -ContainerCache- procedure [mark: Mark] 

RETURNS [index: oikROiNAL]; 
Info: -Cursor- TYPE = record [type: Type, hotX: (0..151, hotY: [0..151]; 
Info: -FUeContainerSource- procedure [source: ContainerSource.Handle] 

returns [ 

file: NSFile. Reference, columns: ColumnContents, scope: NSFile.Scope, 
options: Options]; 
Info: "SoftKeys^ procedure [window: Window.Handle] 
returns [ 

table: TIP. Table, notifyProc: TIP.NotifyProc, labels: Labels, 
highiightedKey: cardinal, outlinedKey: cardinal]; 

InitBreakTabie: -XString- procedure [ 

r: Reader, stopOrNot: StopOrNot, otherSets: StopOrNot] 
RETURNS [break: BreakTableObject]; 

Initiallze: -Window- procedure [ 

window: Handle, display: DisplayProc, box: Box, parent: Handle "rootWindow, 
sibling: Handle 'nil, child: Handle 'nil, clearingRequired: boolean 'true, 
windowPane: boolean "false, under: boolean 'false, cookie: boolean 'false, 
color: BOOLEAN 'false); 

InitiaiizeWindow: -Window- procedure [ 

window: Handle, display: DisplayProc, box: Box, parent: Handle 'rootWindow, 
sibling: Handle 'nil, child: Handle 'NiL,clearingRequired: boolean 'true, 
windowPane: boolean 'false, under: boolean 'false, cookie: boolean 'false, 

color: BOOLEAN 'FALSE]; 

InsertlntoTree: -Window- procedure [window: Handle]; 
Insertltem: -ContainerCache- procedure [ 

cache: Handle, before: cardinal, addData: AddOata] 

RETURNS [handle: ItemHandle]; 
Insertltem: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, line: Line, beforeltem: ItemKey, 

preMargin: cardinal '0, tabStop: cardinal 'nextTabStop, 

repaint: boolean 'true); 
InsertLine: -FormWindow- procedure [ 

window: Window.Handle, before: Line, spaceAboveLine: cardinal '0] 

RETURNS [line: Line]; 

InstailBody: -5tdrW/ndow5he//~ procedure [sws: Handle, body: Window.Handle]; 

InstallFormWindow: -PropertySiieet- procedure [ 

shell: StarWindowShel I. Handle, menultemProc: MenultemProc, 

menultems: Menultems 'propertySheetOefaultMenu, title: XString. Reader 'nil, 

formWindow: Window.Handle, afterTakenOownProc: MenultemProc 'nil]; 

InsufficientRoom: -XString- signal ( 

needsMoreRoom: Writer, amountNeeded: cardinal]; 

IntegerPart: -XLReal- procedure [Number] returns [Number]; 

Interpolator: -Display- Vfp^ « record [val: FixdPtNum,dVal: FixdPtNum]; 

IntersectBoxes: -W/ndow~ procedure [b1: Box, b2: Box] returns [box: Box]; 

Invalid: -XTime- error; 

InvaiidateBox: -Window- procedure [ 

window: Handle, box: Box, clarity: Clarity 'isDirty]; 

InvaiidateCache: -Conta/nee- procedure [data: DataHandle]; 

InvalidateWholeCache: -Containee- procedure; 

InvalidEncoding: -XString- error [ 

invalid Reader: Reader, firstBadByteOffset: cardinal]; 

InvalidHandle: -BlaclcKeys- error; 

InvaiidHandle: -SoftKeys- error; 

InvaiidNumber: -XString— signal; 

InvalidTabte: -HP- signal [type: TabieError, message: XString. Reader]; 
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invert: -Cursor- procedure returns [boolean]; 
Invert: -Display- procedure [ 

window: Handle, box: Window.Box, bounds: Window.BoxHandle *nil]; 
isBitmapUnderVariant: -Window- procedure [Handle] returns [boolean]; 
IsBodyWindowOutOflnterior: -StarUWndowShe//- procedure [body: Window. Handle] 

RETURNS [boolean]; 

IsCloseLegal: -StarW/nc/owS/ie//- procedure [ 

sws: Handle, closeAII: boolean 'false] returns [boolean]; 
IsCloseLegal Proc: -StarW/ndowShe//- TYPE = procedure [ 

sws: Handle, doseAII: boolean >alse] returns [boolean]; 
IsCloseLegalProcReturnsFalse: ~5tarV1^fnofow5/ie//~lsC]oseLegalProc; 
IsColorVariant: -Window- procedure [Handle] returns [boolean]; 
IsCookieVariant: -Window- procedure [Handle] returns [boolean]; 
IsOescendantOfRoot: -Window- procedure [Handle] returns [boolean]; 
IsIt: -ContainerWindow- procedure [window: Window. Handle] 

RETURNS [yes: boolean]; 
Isit: ~F//eConta/nerSoi/rce~i>ROCEDURE [source: ContainerSource.Handle] 

RETURNS [boolean]; 

Isit: -FormWindow- procedure [window: Window. Handle] returns [yes: boolean); 
Isit: -MessageWindow- procedure [Window. Handle] returns [yes: boolean]; 
IsPlaceinBox: -Window- procedure [place: Place, box: Box] returns [boolean]; 
IsSpedai: ~Xi./7ea/~ procedure [Number] 

returns [yes: boolean, index: Special Index]; 
Item: -A/fefJuOafa— TYPE = Privateltem; 

Item: -XTofcen- procedure [h: Handle, temporary: boolean "true] 

RETURNS [value: XString.ReaderBody]; 
ItemOfents: -Conta/nefCac/»e~ PROCEDURE [item: ItemHandle] jm^ 

RETURNS [clientData: LONG pointer]; 
itemClientsLength: -ContainerCache- procedure [handle: Item Handle] 

RETURNS [dataLength: cardinal]; 
ItemOata: -MenuData- procedure [item: ItemHandle] returns [long unspecified); 
ItemGeneric: -ContainerSource- ItemGenericProc; 
ItemGenericProc: -Conta/nerSoi/rce- type = procedure [ 

source: Handle, itemlndex: Itemlndex, atom: Atom.ATOM, 

changeProc: ChangeProc "nil, changeProcData: long pointer "nil] 

returns [long unspecified]; 
ItemHandle: -Conta/nerCac/»e~ TYPE a LONG POINTER TO ItemObject; 
ItemHandle: -MenuData- type = long pointer to Item; 
Itemlndex: -ContainerCache- procedure [item: ItemHandle] 

RETURNS [index: cardinal]; 
Itemlndex: ~Conta/ner5ource- TYPE = cardinal; 
ItemKey: -FormWindow- type = cardinal; 
ItemName: -MenuData- procedure [item: ItemHandle] 

RETURNS [name: XString.ReaderBody]; 
ItemNameWldth: -A/fenuData- procedure [item: ItemHandle] returns [cardinal]; 
ItemNthString: -ContainerCaclie- procedure [item: ItemHandle, n: cardinal] 

returns [XStnng.ReaderBody); 
ItemObject: -ContainerCache- type; 

ItemProc: -MenuData- procedure [item: ItemHandle] returns [proc: MenuProc]; 
ItemStringCount: -Conta/nerCac/ie- procedure [item: ItemHandle] 

RETURNS [strings: cardinal]; 
ItemType: -FormWindow- type = machine dependent{ 

choice, multiplechoice, decimal, integer, boolean, text, command, tagonly, 

window, last(1S)}; 
JoinDirection: -XC/iar-TYPE = {nextCharToRight, nextCharToLeft}; 
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KeyBits: ~Z.eve//V/Ceys- TYPE = packed array Key Name of Down Up; 
KeyBits: ~r/P- TYPE = LevellVKeys.KeyBits; 

Keyboard: -S/ac/c/Ceys- type = long pointer to KeyboardObject "nil; 

KeyboardClass: -KeyboardKey- type. = {system, client, special, all, none}; 

KeyboardObject: -BlackKeys- type « record [ 
table: TIP.Table "nil, 
charTranslator: TIP.CharTranslator "xxx, 
pictureProc: PictureProc "nil, 
label: XString.ReaderBody 'xxx, 
clientData: long pointer "nilI; 

KeyName: -Leve/ZV/Ceys-TYPE s machine depenoent{ 

notAKey, Keyset1(8), Keyset2, Keysets, Keyset4, Keysets, MouseLeft, 
MouseRight, MouseMiddle, Five, Four, Six, E, Seven, D, U, V, Zero, K, Minus, 
P, Slash, Font, Same, BS, Three, Two, W, Q, S, A, Nine, I, X, O, L, Comma, 
CloseQuote, RightBracket, Open, Keyboard, One, Tab, ParaTab, F, Props, C, J, 
B, Z, LeftShift, Period, SemiColon, NewPara, OpenQuote, Delete, Next, R, T, G, 
Y, H, Eight, N, M, Lock, Space, LeftBracket, Equal, RightShift, Stop, Move, 
Undo, Margins, R9, L10, L7, L4, LI, A9, RIO, A8, Copy, Find, Again, Help, 
Expand, R4, D2, D1, Center, T1, Bold, Italics, Underline, Superscript, 
Subscript, Smaller, T10, R3, Key47, AlO, Defaults, A1 1, A12}; 

KeyName: -f/P- TYPE a Level I VKeys. Key Name; 

Keys: -XComSoftMessage- type = machine dependent{ 
time, date, dateAndTime, am, pm, January, february, march, april, may, june, 
juiy, august, September, October, november, december, monday, tuesday, 
Wednesday, thursday, friday, Saturday, Sunday, decimal Separator, 
thousandsSeparator}; 

Keystations: -KeyboardWindow- type = machine dependent{ 

k1, k2, k3, k4, k5, k6, k7, kS, k9, klO, k1 1, k12, k13, k14, k15, k16, k17, 
kia, k19, k20, k21, k22, k23, k24, k25, k26, k27, k28, k29, k30, k31, k32. 
k33; k34, k35, k36, k37. k38, k39, k40, k41 , k42, k43, k44, k45, k46, k47, 
k48, a1, a2, a3, a4, aS, a6, a7, a8, a9, alO, all, a 12, last(96)}; 

KeyToCharProc: -TIP- type = procedure [ 

keys: long pointer to KeyBits, key: KeyName, downUp: DownUp, 
data: long pointer, buffer: XString. Writer J; 

Label Record : -Soft/feys- type « record [ 

unshifted: XString.ReaderBody "xxx, shifted: XString.ReaderBody "xxxj; 

Labels: -SoftKeys- type s long descriptor for array cardinal of Label Record; 

lasstOldApplicationSpecific: -BWSAttributeTypes- 
NSFile.ExtendedAttributeType = 10457B; 

lastBWSType: -BWSAttributeTypes- NSFile.ExtendedAttributeType s T0777B; 

LayoutError: -FormWindow- signal [code: LayoutErrorCode]; 

LayoutErrorCode: -FormWindow-VfPB = {onTopOfAnotherltem, notEnufTabsDefined}; 
LayoutlnfpFromitem: -FormWindow^ procedure [ 
window: Window. Handle, item: Item Key] 

RETURNS [line: Line, margin: cardinal, tabStop: cardinal, box: Window.Box]; 
LayoutProc: -FormWindow- type = procedure [ 

window: Window.Handle, clientData: long pointer]; 
Less: -XiReal- procedure [a: Number, b: Number] returns [boolean]; 
LessEq: -XiReal- procedure [a: Number, b: Number] returns [boolean]; 
LimitProc: "StarWindowShell-TfPB = procedure [sws: Handle, box: Window.Box] 

RETURNS [Window.Box]; 
Line: -Display- procedure [ 

window: Handle, start: Window.Place, stop: Window.Place, 

lineStyle: LineStyle "imil, bounds: Window. BoxHandle "nil]; 
Line: -FormWindow- tvp^ [2]; 
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Line: -XFormat- procedure [ 

h: Handle "nil, r: XString. Reader, n: cardinal "1]; 
Line: -XToken- FilterProcType; 

LineStyle: -Oisp/ay- TYPE = long pointer to LineStyleObject; 
LineStyleObject: -Display- TfP£ s record [ 

widths: array [0..5] of cardinal, thickness: cardinal]; 
UneUpBoxes: -FoimWindow- procedure [ 

window: Window. Handle, 

items: long descriptor for arra y cardinal of Item Key "xxxj; 
Ln: -XLReal- procedure [Number] returns [Number]; 
Log: -XLReai- procedure [base: Number, arg: Number] returns [Number]; 
logoff: -StarOesitftop- Atom.ATOM; 
logon: -StarOes/ctop- Atom.ATOM; 

LogonSession: -BWSZone- procedure returns [uncounted zone]; 
logonSession: -BWSZone- uncounted zone; 
LookAtTextltemVaiue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey] returns [value: XString.ReaderBody]; 
Lop: -XString- procedure [r: Reader] returns [c: Character]; 
LosingFocusProc: -HP-type = procedure ( 

w: Window.Handle, data: long pointer]; 
Lowercase: -XChar- procedure [c: Character] returns [Character]; 
LTP: -XTtme- type = record [ 

r: SELEat: *FROM 

useSystem = > null, useThese s > [Itp: System. LocalTimeParameters], enocase]; 
maiiStatus: -SWSAttr/buterypes- NSFile.ExtendedAttributeType = 104118; 
Make: -Atom- procedure [pName: XString. Reader] returns [atom: atom]; 
Make: -XChar- procedure [set: Environment.Byte, code: Environment.ByteJ 

RETURNS [Character]; 
Make: -XCharSetO- procedure [code: CodesOl returns [XChar. Character]; 
Make: -XCharSetl64- procedure [code: Codes164] returns [XChar. Character]; 
Make: -XCharSet356- procedure (code: Codes3561 returns [XChar. Character]; 
Make: -XCharSet357- procedure (code: Codes3571 returns [XChar.Character]; 
Make: -XCharSet360~ procedure [code: Codes360] returns [XChar.Character]; 
Make: ~XChar5et361- procedure (code: Codes361] returns [XChar.Character]; 
Make: -XC/)ar5et4 7- procedure [code: Codes41] returns [XChar.Character]; 
Make: -XCharSet42- procedure (code: Codes42] returns [XChar.Character]; 
Make: -XC/7arSet43- procedure (code: Codes43] returns [XChar.Character]; 
Make: -XChar5et44- procedure [code: Codes44] returns [XChar.Character]; 
Make: -XCharSet45- procedure [code: Codes45] returns [XChar.Character]; 
Make: -XCharSet46- procedure [code: Codes46j returns [XChar.Character]; 
Make: -XCharSet47- procedure (code: Codes47] returns [XChar.Character]; 
MakeAtom: -Atom- procedure [pName: long string] returns [atom: atom]; 
MakeBooieanltem: -FormWindow— procedure [ 

window: Window.Handle, myKey: ItemKey, tag: XString. Reader 'nil, 

suffix: XString. Reader 'nil, visibility: Visibility 'visible, 

boxed: boolean 'true, readonly: boolean "false, 

changeProc: BooieanChangeProc 'nil, label: BooleanltemLabel, 

initBoolean: boolean 'true]; 
MakeChoiceltem: -FormWindow- procedure [ 

window: Window.Handle, myKey: ItemKey, tag: XString. Reader 'nil, 

suffix: XString. Reader 'nil, visibility: Visibility 'visible, 

boxed: boolean 'true, readonly: boolean 'false, values: Chotceltems, 

initChoice: Choicelndex, fullyOisplayed: boolean 'true, 

verticallyOisplayed: boolean 'false, hintsProc: ChoiceHintsProc 'nil, 

changeProc: ChoiceChangeProc "nil, 

outiineOrHighlight: OutlineOrHighlight 'highlight]; 
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MakeCommandltem: -FarmWindow— procedure [ 

window: Window. Handle, myKey: ItemKey, tag: XString. Reader 'nil, 
suffix: XString. Reader *nil, visibility: Visibility 'visible, 

boxed: boolean "true, readonly: boolean 'false, commandProc: CommandProc, 
command Name: XString.Reader, dientOata: long pointer 'nil]; 

MakeOedmalltem: "FormWindoW" procedure [ 
window: Window. Handle, myKey: ItemKey, tag: XString. Reader 'nil, 
suffix: XString.Reader 'nil, visibility: Visibility 'visible, 
boxed: boolean 'true, readonly: boolean 'false, signed: boolean 'false, 
width: cardinal, initOecimal: XLReal. Number 'xxx, 
wrapUnderTag: boolean 'false, hintsProc: TextHintsProc 'nil, 
nextOutOfProc: NextOutOfProc 'nil, dispiayTempiate: XString.Reader 'nil, 
SPECIALKeyboard: BlackKeys. Keyboard 'nil]; 

Makelntegeritem: -FormWrndow- procedure [ 
window: Window. Handle, myKey: ItemKey, tag: XString.Reader 'nil, 
suffix: XString.Reader 'imil, visibility: Visibility 'visible, 
boxed: boolean 'true, readonly: boolean 'false, signed: boolean 'false, 
width: cardinal, initlnteger: long integer '0, wrapUnderTag: boolean 'false, 
hintsProc: TextHintsProc 'nil, nextOutOfProc: NextOutOfProc 'nil, 
SPECIALKeyboard: BiackKeys.Keyboard 'nil]; 

MakeltemsProc: -FormW'mdow^ type = procedure ( 
window: Window. Handle, clientOata: long pointer]; 

MakeMenultem: -FomiV^/ndow- procedure [ 

window: Window. Handle, myKey: ItemKey, tag: XString.Reader 'nil, 
suffix: XString.Reader 'nil, visibility: Visibility 'visible, 
boxed: boolean 'true, menu: MenuOata.MenuHandle]; 

MakeMultipleChoiceltem: -FormWindow— procedure [ 

window: Window. Handle, myKey: ItemKey, tag: XString.Reader 'nil, 
suffix: XString.Reader 'nil, visibility: Visibility 'visible, 
boxed: boolean 'true, readonly: boolean 'false, values: Choiceltems, 
initChoice: long descriptor for array cardinal of Choicelndex, 
fullyDisplayed: boolean 'true, verticallyOisplayed: boolean "false, 
hintsProc: ChoiceHintsProc "NiL,changeProc: MultipleChoiceChangeProc "nil, 
outlineOrHighlight: OutlineOrHighlight 'highlight]; 

MakeNegative: -Cursor- procedure; 

MakePositive: -Cursor- procedure; 

MakeSpecial: -XLReal- procedure [index: Special Index] returns [Number]; 

MakeTagOnlyltem: -Form Window- procedure [ 
window: Window. Handle, myKey: ItemKey, tag: XString.Reader, 
visibility: Visibility 'visible]; 

MakeTextltem: -FormWindow- procedure [ 
window: Window. Handle, myKey: ItemKey, tag: XString.Reader 'nil, 
suffix: XString.Reader "nil, visibility: Visibility 'visible, 
boxed: boolean 'true, readonly: boolean 'false, width: cardinal, 
initString: XString.Reader "nil, wrapUnderTag: boolean "false, 
passwordFeedback: boolean "false, hintsProc: TextHintsProc "nil, 
nextOutOfProc: NextOutOfProc 'nil, 
SPECIALKeyboard: Black Keys. Keyboard 'nil]; 

MakeWindowltem: -Form W/ndow- procedure [ 

window: Window. Handle, myKey: ItemKey, tag: XString.Reader 'nil, 
visibility: Visibility "visible, boxed: boolean 'true, size: Window.Dims, 
nextlntoProc: NextlntoProc "nil] returns [clientWindow: Window.Handle]; 

Manager: -TIP- type = record [ * 

table: Table, window: Window.Handle, notify: NotifyProc]; 

Manager Data: -Selection- type = long pointer; 
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Map: -XString- procedure [r: Reader, proc: MapCharProc] 

RETURNS [c: Character]; 
MapAtomProc: -Atom- type = procedure [atom] returns [boolean]; 
MapAtoms: -Atom- procedure [proc: MapAtomProc] returns [lastAtom: atom]; 
MapCharProc: -XString- type = procedure [c: Character] 

returns [stop: boolean]; 
MappedDefaultFont: -SimpleTextFont- procedure returns [MappedFontHandte]; 
MappedFont: "SimpleTextFont- procedure [name: XString.Reader 'nil] 

RETURNS [MappedFontHandte]; 
MappedFontOescriptor: -SimpleTextFont- type; 
MappedFontHandte: -SimpieTextFont- type s long pointer to 

Mapped FontOescri ptor; 
MapPList: -Atom- procedure [atom: atom, proc: MapPListProc] 

RETURNS [iastPair: RefPair]; 
MapPListProc: -Atom- type = procedure [RefPair] returns [boolean]; 
Mark: -ContainerCache- type s long pointer to MarkObject; 
MarkObject: -ContainerCache- type; 

Match: -Se/ect/on- procedure [pointer: ManagerData] returns [match: boolean]; 
maxString Length: ~Se/ect/on~ cardinal = 200; 
MaybeQuoted: -XToken- procedure [ 

h: Handle, data: FilterState, filter: FilterProcType ' NonWhiteSpace, 

isQuote: QuoteProcType 'Quote, skip: SkipMode 'whiteSpace, 

temporary: boolean "true] returns (value: XString.ReaderBodYl; 
MeasureString: -S/mp/erextO/sp/ay- PROCEDURE [ 

string: XString.Reader, lineWidth: cardinal " 1 77777B, 

wordBreak: boolean "true, streakSuccession: StreakSuccession "fromFirstChar, 

font: SimpleTextFont.MappedFontHandle "nil] 

returns [width: cardinal, result: Result, rest: XString.ReaderBody]; 
MenuArray: -MenuData- procedure [menu: MenuHandle] 

RETURNS [array: ArrayHandle]; 
MenuEnumProc: -StarWindowShell- typb = procedure [menu: MenuData. MenuHandle] 

RETURNS [stop: BOOLEAN "FALSE); 

MenuHandle: -MenuData- type = long pointer to MenuObject; 
MenultemProc: -PropertySheet- type = procedure [ 

shell: StarWindowSheil. Handle, formWindow: Window. Handle, 

menultem: MenultemType, dientOata: long pointer] returns [ok: boolean]; 
Menultems: -PropertySheet- type « packed array MenultemType of 

BooleanFalseOefault; 
MenultemType: -PropertySheet- type = { 

done, apply, cancel, defaults, start, reset}; 
MenuObject: -MenuData- type = PrivateMenu; 
MenuProc: -MenuData- type = procedure ( 

window: Window.Handle, menu: MenuHandle, itemData: long unspecified]; 
MenuTltle: -MenuData- procedure [menu: MenuHandle] 

RETURNS [title: itemHandle]; 
Messages: -XMessage- type = long descriptor for array cardinal of Msg Entry; 
MessagesFromFile: -XMessage- procedure [ 

fileName: long string, clientOata: ClientData, proc: OestroyMsgsProc] 

returns [msgOomains: MsgDomains]; 
MessagesFrom Reference: -XMessage- procedure [ 

file: NSFile. Reference, clientData: ClientData, proc: OestroyMsgsProc] 

returns [msgDomains: MsgDomains]; 
MinDimsChangeProc: -Form W/ndow- type = procedure [ 

window: Window.Handle, old: Window.Dims, new: Window.Dims]; 
MinusLandBltmapUnder: -Window- type [6]; 
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MinusLandColor: -Window- typb [1]; 
MinusLandCookieCutter: -Window- Tvpe (21; 
Mode: -TIPStar-VfPE = {normal, copy, move, sameAs}; 
ModeOiangeProc: -TIPStar- type = procedure [ 

old: Mode, new: Mode, dientData: long pointer]; 
ModlfySource: -ContainerWindow— procedure [ 

window: Window. Handle, proc: SourceModifyProcJ; 
Months: -XComSoftMessage- type = Keys [january..december]; 
MoreFlavor: -StarWindowShell- type a {before, after}; 
MoreScrollProc: -StarWindowShell- type a procedure [ 

sws: Handle, vertical: boolean, flavor: MoreFlavor, amount: cardinal]; 
MouseTransformerProc: -Window- type s procedure [Handle, Place] 

returns [Handle, Place]; 
Move: -Selection- procedure [v: ValueHandle, data: long pointer]; 
MovelntoWindow: -Cursor- procedure ( 

window: Window. Handle, place: Window.Place]; 
MoveMark: -ContainerCache— procedure [mark: Mark, newlndex: cardinal]; 
MsgDomain: -XMessage- type s record [ 

applicationName: XString.ReaderBody, handle: Handle]; 
MsgOomains: -XMessage- type a long descriptor for array cardinal of MsgOomain; 
MsgEntry: -XMessage- type = record [ 

msgKey: MsgKey, 

msg: XString.ReaderBody, 

translationNote: long string "nil, 

translatable: boolean tTRUE, 

type: MsgType 'userMsg, 

id: MsgID]; 
MsgiD: -XMessage- type = cardinal; 
MsgKey: -X/Wessage- TYPE = cardinal; 

MsgKeyList: -XMessage- type = long descriptor for array cardinal of MsgKey; 
MsgType: -XMessage- type = { 

userMsg, template, argList, menultem, pSheetltem, commandltem, errorMsg, 

infoMsg, promptltem, windowMenuCommand, others}; 
Multi Attn buteFormatProc: -f/VeContamerSource- TYPE = procedure I 

containeeimpi: Containee.lmplementation, containeeOata: Containee.OataHandle, 

attrRecord: NS File. Attributes, displayString: XString.Writer]; 
MultipleOioiceChangeProc: -FormW/ncfow-TYPE = procedure [ 

window: Window. Handle, item: ItemKey, calledBecauseOf: ChangeReason, 

oldVaiue: long descriptor for array cardinal of Choicelndex, 

newValue: long descriptor for array cardinal of Choicelndex]; 
Multiply: -XLReal- procedure [a: Number, b: Number] returns [Number]; 
NameAndVersionColumn: -FileContainerSourceBxtra- procedure 

returns [multipleAttributesFileContainerSource.ColumnContentslnfo]; 
NameColumn: -FileContainerSource- procedure 

returns [attribute ColumnContentslnfo]; 
NeededOlms: -FormWindow- procedure [window: Window.Handle] 

returns [Window.Dims]; 
Negative: -XLReal- procedure [Number] returns [Number]; 
netAddr: ~8VI^5Attr/buterypes~ NSFile.ExtendedAttributeType = 10402B; 
NetFormat: -XFormat- type = {octal, hex, productSoftware}; 
NetworkAddress: -XFormat- procedure [ 

h: Handle "nil, networkAddress: System. NetworkAddress, format: NetFormat]; 
networkName: -SWSAttr/bute fypes-- NSFile.ExtendedAttributeType = 10404B; 
NetworkNumber: -XFormat- procedure ( 

h: Handle "nil, networkNumber: System.NetworkNumber, format: NetFormat]; 
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New: "Window- procedure [ 

under: boolean 'pause, cookie: boolean "false, color: boolean >alse, 

zone: uncounted zone "LOOPHOLE[01] returns [Handle]; 
newlcon: -StarDesktop- Atom.ATOM; 

NewResolveBuffer: SimpieTextDisplay" procedure [words: cardinal] 

returns [ResolveBufferJ; 
NewStandardCloseEverythIng: -StarWindowSheUExtra— procedure 

returns [ 

numberLeftOpen: cardinal *0, 

lastNotaosed: StarWIndowShell.Handle 'LOOPHOLE[0]]; 
NewWrlterBody: -XString^ procedure [maxLength: cardinal, z: uncounted zone] 

RETURNS [WriterBody]; 
NextlntoProc: -FormWindow- type = procedure [ 

window: Window. Handle, item: ItemKey]; 
NextOutOfProc: -FormWindow- type = procedure ( 

window: Window, Handle, item: ItemKeyJ; 
nextPlace: -StarDesktop- Window.Place; 
nextTabStop: -Form Window- CARDINAL = 177777B; 
NllData: -XToken- signal; 
nonQuote: -XTo/cen— XChar. Character = 0; 
NonWhiteSpace: -XToken— FilterProcType; 
NopDestroyProc: -Context- DestroyProcType; 
NopFree: -Selection- ValueFreeProc; 

nopFreeValueProcs: -Selection- readonly long pointer to ValueProcs; 

NormalTable: -TIPStar- procedure returns (TIP.TableJ; 

noScrol I Data : -StarWindowShell— Scrol I Data ; 

NoSuchAtom: -Atom- error; 

NoSuchDependency: —Event— error; 

not: -XC/iar- Character = T77777B; 

noTabStop: -Form Window- cardinal = 177776B; 

NotAProfileFlle: -OptionFile- signal; 

NotEq: -XLReal- procedure [a: Number, b: Number] returns [boolean]; 
Notes: -XTime- type = { 

normal, nozone, zonedGuessed, noTime, timeAndZoneGuessed}; 
Notify: -Event- procedure [event: EventType, eventData: long pointer "nil] 

RETURNS [veto: boolean]; 
NotifyProc: -77P~type s procedure [window: Window. Handle, results: Results]; 
NSChar: -XFormat- procedure [h: Handle "nil, char: NSString. Character]; 
NSLine: -XFormat- procedure [ 

h: Handle "nil, s: NSString.String, n: cardinal * 1 ]; 
NSString: -XFormat- procedure [h: Handle "nil, s: NSString.String]; 
NSStringFromReader: -XString- procedure [r: Reader, z: uncounted zone] 

RETURNS [ns: NSString.String]; 
NSStringObject: -XFormat- procedure [s: long pointer to NSString.String] 

RETURNS [Object]; 
SStringProc: -XFormat- FormatProc; 
NthCharacter: -XString- procedure [r: Reader, n: cardinal] 

RETURNS [c: Character]; 
null : -Atom- atom; 
null: -XC/iar- Character = 0; 
null Box: -Window- Box; 
null Data: -Containee- Data; 
null Handle: -StarWindowShell- Handle; 
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null Item : -ContainerSource- Item I ndex a 1 77777B ; 
nullltemKey: -FormW/ndoiV" ItemKey = 177777B; 
null Key: -So/t/feys- CARDINAL = 177777B; 
null Manager: -T7P- Manager; 
nullOption: -ProductFactoring- Option; 
nullPericdicNotify: -77P- PeriodicNotify; 
nullPicture: -BlackKeys- bitmap Picture; 
nullPlace: -PropertySheet- Window.Place; 
null Prerequisite: -ProductFactoring- Prerequisite; 
nullReaderBody: -XString- ReaderBody; 
nullValue: ~5e/ect/on~ Value; 
nullWriterBody: -XString- WriterBody; 
Number: -XFormat- procedure [ 

h: Handle *nil, n: long unspecified, format: NumberFormat]; 
Number: -XI./?ea/~ type [4]; 
Number: -xroilfe/T-- procedure [ 

h: Handle, radix: cardinal, signal On Error: boolean "true] 

returns [u: long unspecified]; 

NumberFormat: -XFormat- type a record [ 

base: [2..36JM2, 

zerofill: boolean "false, 

signed: boolean "false, 

columns: [0..255] "OJ; 

NumberOfltems: -FormWindow— procedure [window: Window.Handle] 
returns [cardinal]; 

numberOfKeys: -SoftKeys- cardinal = 8; 

NumberToPair: "XLReal- procedure [n: Number, digits: [ 1 .. 1 3]] 

RETURNS [negative: boolean, exp: integer, mantissa: Digits]; 

Numeric: -XToken- FilterProcType; 

Object: -ContainerCache- type; 

Object: -Cursor- type = record [info: Info, array: UserTerminal.CursorArray]; 
Object: -W/ndow-iYPE [19]; 
Object: -XFormat- type = record [ 
proc: FormatProc, 

context: XString. Context "LOOPHOLE[0], 
data: CllentData "nil]; 
Object: -XMessage- type; 

Object: -XToken- type = machine dependent record [ 
getChar(0:0..31): GetCharProcType, break(2:0..15): XChar.Character *0]; 
ObscuredBySibling: -Window— procedure [Handle] returns [boolean]; 
Octal: -XFormat- procedure [h: Handle "nil, n: long unspecified]; 
Octal: -XTbilre/i- PROCEDURE [h: Handle, signalOnError: boolean "true] 

RETURNS [C: LONG CARDINAL]; 

Octal Format: -XFormat- NumberFormat; 

oidDateSent: -8WSAttr/buterypes- NSFile.ExtendedAttributeType a 10413B; 
Open: -Cata/og- procedure [ 

catalogType: NSFIIe.Type, session: NSFile.Session "LOOPHOLE[0]] 

RETURNS [catalog: NSFtle.Handle]; 
Opportunity: -Undo- Proc; 
Option: -ProcfuctFactor/ng- TYPE a record [ 

product: Product, productOption: ProductOption]; 
Options: -FileContainerSource- type = record [readonly: boolean "false]; 
optionSheetDefaultMenu: -PropertySheet- Menultems; 

outbasketPSData : -BWSA ttributeTypes- NSFi i e. ExtendedAttri butely pe a 1 04 1 0B ; 
OutlineOrHighlight: -FormW/ndow- TYPE a {outline, highlight}; 
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OutlineThisKey: -SoftKeys- procedure ( 

window: Window. Handle, key: cardinal "nullKey]; 
Overflow: -XString- signal; 

owner: -SWS/Attriboterypes- NSFile.ExtendedAttributeType = 10377B; 
Pack: -XTime- procedure [unpacked: Unpacked, useSystemLTP: boolean 'true] 

RETURNS [time: System.GreenwichMeanTime]; 
Packed: -X77me- TYPE = System.GreenwichMeanTime; 
paintFlags: "Display- BitBltFlags; 
paintGrayFlags: -Display- BitBltFlags; 
Pair: -Atom- type s record [prop: atom, value: RefAnyJ; 
PaifToNumber: -XLReal- procedure [ 

negative: boolean, exp: integer, mantissa: Digits] returns [n: Number]; 
Parallelogram: -0/sp/ay- TYPE = record [ 

x: Interpolator, y: integer, w: natural, h: natural]; 
ParseChoiceitemMessage: -FarmWindowMessageParse- procedure [ 

choiceltemMessage: XString. Reader, zone: uncounted zone] 

returns [choiceltems: FormWindow.Choiceltems]; 
ParseReader: -XT7me- procedure [ 

r: XString. Reader, treatNumbersAs: TreatNumbersAs "dayMonthYear] 

returns [time: System.GreenwichMeanTime, notes: Notes, length: cardinal]; 
ParseWith Template: -XT7me- procedure [ 

r: XString. Reader, template: XString. Reader] 

RETURNS [time: System.GreenwichMeanTime, notes: Notes, length: cardinal]; 
PeekForFlushness: -SimpieTextDisplay— procedure [ 

requested Flushness: Flushness, string: XString. Reader] returns [Fiushness]; 
PeekForStreakSuccession : -SimpleTextDispfay- procedure [ 

requestedStreakSuccession: StreakSuccession, string: XString. Reader] 

RETURNS [StreakSuccession]; 
PeriodicNotify: -TIP- type [1 ]; 

Permanent: -BWSZone- procedure returns [uncounted zone]; 
permanent: -BWSZone- uncounted zone; 
PFonts: -ProductFactoringProducts- Product = 4; 
Pi: -XLReal- procedure returns [Number]; 
Picture: -BlackKeys- type = record [ 

variant: select type: PictureType from 

bitmap s > [bitmap: long pointer], text s > [text: XString. Reader], endcase]; 
PictureAction: -B/adr/feys-TYPE s {acquire, release}; 
PictureProc: -BlackKeys- VfP£ = procedure ( 

keyboard: Keyboard, action: PictureAction] 

returns [picture: Picture 'nullPicture, geometry: GeometryTable 'nil]; 
PictureProc: -Containee- type s procedure [ 

data: DataHandle, window: Window. Handle, box: Window.Box, old: PictureState, 

new: PictureState]; 
PictureReal: -XLReal- procedure [ 

h: XFormat.Handle 'nil, r: Number, template: XString. Reader]; 
PictureState: -Containee- type s { 

garbage, normal, highlighted, ghost, reference, referenceHighlighted}; 
PictureType: -BlackKeys- type = {bitmap, text}; 

Piece: -XString- procedure [r: Reader, firstChar: cardinal, nChars: cardinal] 

returns [piece: ReaderBody, endContext: Context]; 
Place: ~W/ndow- type = UserTerminal.Coordinate; 
Placeholder: -TIPStar- type = { 

mouseActions, keyOverrides, softKeys, keyboardSpecific, blackKeys, sideKeys, 

backstopSpecial Focus}; 
Point: -Display- procedure [window: Handle, point: Window. Place]; 
Pop: -StarWindowShell- procedure [popee: Handle] returns [Handle]; 
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PopOrSwap: -StarWindowShell- type = {pop, swap}; 
^ PoppedProc: StarWindowShell- type = procedure [ 

popped: Handle, newSheii: Handle, popOrSwap: PopOrSwap ^pop]; 
PopTabie: -TlPStar- procedure [Placeholder, TIP. Table]; 
Popup: "PopupMenu-- procedure [ 

menu: MenuOata.MenuHandle, clients: Window. Handle, showTitle: boolean 'true, 

place: Window.Place *LOOPHOLEC37777777777Bl]; 
Post: -Attention^ procedure [ 

s: XString.Reader, clear: boolean 'true, beep: boolean "false, 

blink: boolean 'false]; 
Post: -MessageWindow- procedure [ 

window: Window. Handle, r: XString.Reader, clear: boolean 'true]; 
PostAndConfirm: -Attention- procedure [ 

s: XString.Reader, clear: boolean 'true, 

confirmChoices: ConfirmChoices 'xxx, timeout: Process.Ticks "dontTimeout, 

beep: boolean 'false, blink: boolean "false] 

returns [confirmed: boolean, timedOut: boolean]; 
PostSticky: -Attention- procedure [ 

s: XString.Reader, clear: boolean "true, beep: boolean "false, 

blink: boolean "false]; 
PostSTRING: -MessageWindow- procedure [ 

window: Window. Handle, s: long string, clear: boolean "true]; 
Power: -X£/7ed/- procedure [base: Number, exponent: Number] returns [Number]; 
Prerequisite: -ProductFactoring- type = record [ 

prerequisiteSpec: BOOLEAN "false, option: Option]; 
printingLigatures: -XC/»arSet360~XCharSets.Sets = LOOPHOLE[240]; 
Privateltem: -MenuOata- TYPE a PRIVATE RECORD [ 

proc: MenuProc, 

nameWidth: natural, 

nameBytes: natural, 

body: select hasltemOata: boolean from 

FALSE = > [name: packed sequence computed cardinal of Environment. Byte], 
TRUEs>[ 

item Data: long unspecified, 

name: packed sequence computed cardinal of Environment.Byte], 
endcase]; 

PrivateMenu: -MenuData- ty^e « private record [ 

zone: uncounted zone, 

swapltemProc: SwapltemProc, 

title: ItemHandle "nil, 

array: Array Handle "xxx, 

arrayAllocatedltemHandles: natural "0, 

itemslnMenusZone: boolean "false]; 
Problem: -SimpleTextFont- signal [code: ProblemCode]; 
ProblemCode: -SimpleTextFont- type = { 

badFont, ciientCharacterCodesExhausted, clientCharacterBitsExhausted}; 
Proc: -Undo- type = procedure ( 

undoProc: procedure [long pointer], destroyProc: procedure [long pointer], 

data: long pointer, size: cardinal "0]; 
Procedures: -Conta/nerSoorce- TYPE = long pointer to ProceduresObject; 
ProceduresObject: -ContainerSource-jyPB = record [ 

actOn: ActOnProc, 

canYouTake: CanYouTakeProc, 

columnCount: ColumnCountProc, 

convertltem: Con vert Item Proc, 

deleteltems: DeleteltemsProc, 
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getLength: GetLengthProc, 

itemGeneric: ItemGenericProc, 

stringOfltem: StringOfltemProc, 

take: TakeProc]; 
Product: -ProductFactoring- type s cardinal [0.. 1 51; 
Product: -ProductFactoringProducts-Tf PS = Prod uctFactoring. Product; 
Product: -ProductFactoringProductsExtras- TYPE = ProductFactoring.Product; 
ProductOption: -ProductFactoring- type = cardinal [0..271; 
property SheetDefauitMenu: -PropertySheet- Menu items; 
prototypeCatalog: -aWSf/Zefypes- NSFile.Type a 1; 
PubiicZone: -MenuData- procedure returns [uncounted zone]; 
PurgeOldVersions: -Prototype- procedure [ 

type: NSFile.Type, current: Version, subtype: Subtype "0]; 
Push: -8/ac/(/Ceys~ procedure [keyboard: Keyboard]; 
Push: -SoftKeys- procedure [ 

tabie: TIP.Table "nil, notifyProc: TIP.NotifyProc *nil, 

labels: Labels 'xxx, highllghtedKey: cardinal "nuilKey, 

outiinedKey: cardinal ^nuilKey] returns [window: Window.Handle]; 
Push: -StarWindowSheU- procedure ( 

newShell: Handle, topOfStack: Handle *LOOPHOLE[0]. 

poppedProc: PoppedProc 'nil]; 
PushedMe: ~StarW/ndowSA»e//Extra- procedure [pushee: StarWindowShell. Handle] 

returns [pusher: StarWindowShell. Handle]; 
PushedOnMe: -StarWindowShell Extra- pnocEOURB [pusher: StarWindowShell. Handle] 

RETURNS [pushee: StarWindowShell.Handle]; 
PushTable: -TIPStar- procedure [Placeholder, TIP.Table]; 
PutProp: -Atom— procedure [onto: atom, pair: Pair]; 
Query: -Selection— procedure [ 

targets: long descriptor for array cardinal of QueryElement]; 
QueryElement: -Selection— type = record [ 

target: Target, enumeration: boolean "false, difficulty: Difficulty "null]; 
Quote: -XToken- QuoteProcType; 

QuoteProcType: -XToken- type = procedure [c: XChar. Character] 

returns [closing: XChar.Character]; 
Reader: -XFormat- procedure [h: Handle "nil, r: XString. Reader]; 
Reader: -XString- type = long pointer to ReaderBody; 
ReaderBody: -XFormat- procedure [h: Handle "nil, rb: XString. ReaderBody]; 
ReaderBody: -XString- type a private machine dependent record [ 

context(0:0..15): Context, 

iimit(1:0.. 15): cardinal, 

offset(2:0..15): cardinal, 

bytes(3:0..31): ReadOnlySytes]; 
ReaderFromWriter: -XString- procedure [w: Writer] returns [Reader]; 
Readerlnfo: -XString- procedure [r: Reader] 

returns [context: Context, startsWith377B: boolean]; 
ReaderToHandle: -xro/fen- procedure [r: XString. Reader] returns [h: Handle]; 
ReaderToNumber: -XLReal- procedure [r: XString. Reader] returns [Number]; 
ReaderToNumber: -XString- procedure [ 

r: Reader, radix: cardinal "10, signed: boolean "false] 

RETURNS [long INTEGER]; 

ReadNumber: -XLReal- procedure [ 

get: procedure returns [XChar.Character], 

putback: procedure [XChar.Character]] returns [Number]; 
ReadOnlyBytes: -XString- type = long pointer to readonly ByteSequence; 
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Rebuiidltem: -FileContainerSourceExtraZ- procedure [ 

source: ContainerSource.Handle, item: ContainerSource.ltemindex]; 

Reconversion: ~5e/ect/on~ signal [target: Target, zone: uncounted zone] 
RETURNS [Vaiuel; 

ReconvertDuringEnumerate: Selection^ procedure [ 
target: Target zone: uncounted zone ^LOOPHOLE[0]] returns [Value]; 

Ref Any: -^Atom- type » long pointer; 

referencedType: -^WSAtt/vbutefypes- NSFile.ExtendedAttributeType s 10401B; 
RefPair: -Atom- TYPE a long pointer to readonly Pair; 
refParentID: -aW5Attr/6uterypes~ NSFile.ExtendedAttributeType s 10403B; 
refparentTime: -SWSAttr/buterypes- NSFile.ExtendedAttributeType a 10405B; 
RegisterClientKeyboards: -KeyboardKey- procedure [ 

wantSystem Keyboards: boolean "true, 

SPECIALKeyboard: BlackKeysXeyboard "nil, 

keyboards: long descriptor for array cardinal of BlackKeys.KeyboardObject ^ 
xxx]; 

RegisterMessages: -XMessage- procedure [ 

h: Handle, messages; Messages, strihgBodiesAreReal: boolean]; 
Relation: -XString- type s {less, equal, greater}; 
Release: -Context" procedure [type: Type, window: Window.Handle]; 
Remainder: -XlReal- procedure [a: Number, b: Number] returns [Number]; 
remoteName: -BWSAttributeTypes- NSFile.ExtendedAttributeType = 10406B; 
Remove: -8/ac/(ACeys- procedure [keyboard: Keyboard]; 
Remove: -SoftKeys- procedure [window: Window. Handle]; 
RemoveClientKeyboards: -KeyboardKey- procedure; 
RemoveOependency: -Event- procedure [dependency: Dependency]; 
RemoveFromSystemKeyboards: -/Ceyboarcf/Cey- procedure [ 

keyboard: BlackKeys. Keyboard]; 
RemoveFromTree: -Window- procedure [Handle]; 
Removeitem From Line: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, line: Line, repaint: boolean "true); 
RemoveMenultem: -Attent/on- procedure [item: MenuData.ltemHandle]; 
RemoveProp: -Atom- procedure [onto: atom, prop: atom]; 
Repaint: -formW/ndow— procedure [window: Window.Handle); 
RepaintFteld: -SimpieTextEdit- procedure [f : Field]; 
Replace: -StarWindowSheil Extra- procedure [ 

new: StarWindowShell.Handle, old: StarWindowShell. Handle]; 
ReplaceChars: -SimpieTextEdit- procedure [ 

f: Field, firstChar: cardinal, nChars: cardinal, r: XString. Reader, 

endContext: XString.Context *LOOPHOLE[255], repaint: boolean *true]; 
replaceFiags: -Display- BitBltFlags; 
replaceGrayFlags: -Display- BitBltFlags; 
Replaceltem: -ContainerCache- procedure [ 

cache: Handle, item: cardinal, addOata: AddData] returns [handle: ItemHandle]; 
RepiacePiece: -XString- procedure [ 

w: Writer, firstChar: cardinal, nChars: cardinal, r: Reader, 

endContext: Context *unknownContext]; 
Requestor Data: -Selection- type = long pointer; 

ResetAIIChanged: -FormWindow- procedure [window: Window.Handle]; 
ResetCache: -ContainerCache- procedure [Handle]; 

ResetChanged: -FormWindow- procedure [window: Window.Handle, Item: ItemKey]; 
ResetUserAbort: -T/P- procedure [Window.Handle]; 

ResolveBuffer: -SimpleTextDisplay- type s long descriptor for array [0..0) of 

cardinal; 

Restore: -FormWindow- procedure [window: Window.Handle]; 
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Restore: Selection- procedure [ 

saved: Saved, mark: boolean "true, unmark: boolean "trueI; 
Result: ~S/mp/erextO/sp/ay-- TYPE = {normal, margin, stop}; 
ResultObject: -TIP- type s record ( 
next: Results, 
body: select type: * from 
atom s > [a: atom], 
bufferedChar = > null, 
coords 3 > [place: Window. PI ace], 
int s > [I: L0N<3 integer], 
key 3 > [key: KeyName, downUp: DownUp], 

nop = > NULL, 

string s > [rb: XString.ReaderBody], 
time s > [time: System.Pulses], 

ENDCASE]; 

Results: -TIP- type s long pointer to ResultObject; 
ResultsWanted: -TIPX- type = procedure ( 

window: Window.Handle, table: TIP.Table *nil, results: TIP.Results] 

RETURNS [wanted: boolean]; 
ReturnTicket: -Containee- procedure [ticket: Ticket]; 
ReturnToNotifier: -TIP- error [string: XString. Reader]; 
ReverseLop: -XString- procedure [ 

r: Reader, endContext: long pointer to Context, 

backScan: BackScanClosure "xxx] returns [c: Character]; 
ReyerseMap: -XString- procedure (r: Reader, proc: MapCharProc] 

returns [c: Character]; 

Roadblock: -Undo- procedure [XString. Reader]; 0^ 
root: -eWSF/Verypes- NSFile.Type = 10477B; 
Root: -Window- procedure returns [Handle]; 

Root: -XLReal- procedure [index: Number, arg: Number] returns [Number]; 

rootWindow: -W/ndow— readonly Handle; 

Run: -XString- procedure [r: Reader] returns [run: ReaderBody]; 

Save: -FormWindow- procedure [window: Window.Handie]; 

SaveAndSet: -Selection- procedure ( 

pointer: ManagerOata, conversion: ConvertProc, actOn: ActOnProc, 

unmark: boolean 'true] returns [old: Saved]; 
Saved: -Selection- type [6]; 
Scan: -XString- procedure [ 

r: Reader, break: BreakTable, option: BreakCharOption] 

RETURNS [breakChar: Character, front: ReaderBody]; 
ScanForCharacter: -XString- procedure [ 

r: Reader, char: Character, option: BreakCharOption] 

RETURNS [breakChar: Character, front: ReaderBody]; 
Scroll Data: -StarWindowShell-rypB » record [ 

display Horizontal: boolean "false, 

display Vertical: boolean "false, 

arrowScroll: ArrowScroliProc "nil, 

thumbScroll: ThumbScrollProc "nil, 

moreScrol I : MoreScrol I Proc " nil] ; 
SectionEnumProc: ~Opt/onF/7e~ type = procedure [section: XString. Reader] 

RETURNS [stop: BOOLEAN * FALSE]; 

Selectltem: -ContainerWindow- procedure [ 

window: Window.Handie, item: ContainerSource.ltemlndex]; 'i0tl^^ 
SelectReference: -StarDesktop- procedure [reference: NSFile.Reference] 

RETURNS [ok: boolean]; 
Semipermanent: -BWSZone- procedure returns [uncounted zone]; 
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semipermanent: -BWSZone- uncounted zone; 

Services2: -ProductFactormgProducts£xtras- Product = 8; 

Services: -ProductFactoringProducts- Product = 1 ; 

Set: -Context- procedure [type: Type, data: Data, window: Window.Handle]; 
Set: -Cursor- procedure (type: Defined}; 
Set: -Selection" PRoaDURE [ 

pointer: ManagerData, conversion: ConvertProc, actOn: ActOnProc]; 
Set: -XChar- procedure (c: Character] returns [set: Environment.Byte]; 
SetAdjustProc: "StarWindowSheil— procedure [sws: Handle, proc: AdjustProc] 

RETURNS (old: AdjustProcI; 
SetAllChanged: -Form Window— procedure (window: Window.Handle]; 
SetAttention: -T7P- procedure ( 

window: Window.Handle, attention: Attention Proc]; 
SetBackStoplnputFocus: -TIP- procedure [window: Window.Handle]; 
SetBitmapUnder: -Window- procedure [ 

window: Handle, pointer: long pointer 'nil, 

underChanged: UnderChangedProc "nil, 

mouseTransformer: MouseTransformerProc *nil1 returns [lonq pointer]; 
SetBodyWindowJustFits: -StarW'mdowSheU- procedure ( 

sws: Handle, yes: boolean]; 
SetBOOLEAN: -Atom icPro file- procedure (atom: Atom.ATOM, boolean: boolean]; 
SetBooleanltemVaiue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, newValue: boolean, 

repaint: boolean 'true]; 
SetBottomPusheeCommands: -StarWindowShell- procedure ( 

sws: Handle, commands: MenuOata.MenuHandle]; 
SetCachedName: -Containee- procedure ( 

data: DataHandle, newName: XString. Reader]; 
SetCachedType: -Containee- procedure [data: DataHandle, newType: NSPile.Type]; 
SetChanged: -FormWindow- procedure [window: Window.Handle, item: ItemKey]; 
SetCharTranslator: -TIP- procedure (table: Table,, new: CharTranslator] 

RETURNS (old: CharTranslator]; 
SetChild: -Window- procedure [window: Handle, newChild: Handle] 

RETURNS (oldChiid: Handle]; 
SetChoiceltemVaiue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, newValue: Choicelndex, 

repaint: boolean 'true]; 
SetClearlngRequired: -W^rndow- procedure (window: Handle, required: boolean] 

RETURNS (old: boolean]; 
SetContainee: -StarWindowShell- procedure [ 

sws: Handle, file: Containee.DataHandle]; 
SetDecimalltemValue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, newValue: XLReal. Number, 

repaint: boolean "true]; 
SetDefaultlmplementation: -Containee- procedure (implementation] 

returns [Implementation]; 
SetDefaultOutputSink: -XFormat- PROCEDURE (new: Object] returns (old: Object]; 
SetOesktopProc: -IdleControl- procedure [ 

atom: Atom. atom, desktop: DesktopProc]; 
SetDims: -S/mp/efextfd/t- procedure [f: Field, dims: Window.Dlms]; 
SetDispiayBackgroundProc: -StarDesktop- procedure [procedure [Window.Handle]]; 
SetDispiayProc: -Window- procedure [Handle, DisplayProc] 

returns [DisplayProc]; 

^5^^/ SetFixedHeight: -SimpleTextEdit- procedure [f : Field, fixedHeight: boolean]; 
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SetFlushness: -FormWindow- procedure [ 

window: Window. Handle, item: Item Key, new: Flushnessl 

RETURNS [old: Ftushness]; 
SetFlushness: -SimpieTextEdit- procedure [ 

f: Field, new: SimpleTextOisplay.Flushness] 

returns [old: SimpleTextOisplay.Flushness]; 
SetFont: "SimpleTextEdit" procedure ( 

f: Field, font: SimpleTextFont-MappedFontHandle *nil]; 
SetGlobalChangeProc: -FarmWindow- procedure [ 

window: Window.Handle, proc: GlobalChangeProc] 

returns [old: GlobalChangeProc]; 
SetGreeterProc: -IdleControl- procedure [new: GreeterProc] 

RETURNS [old: GreeterProc]; 
SetHost: -StarW/ndowS/je//- procedure [sws: Handle, host: Handle] 

RETURNS [old: Handle]; 
Setlmpiementation: -Containee- procedure [NSFile.Type, Implementation] 

RETURNS [Implementation]; 
Setlmpiementation: -Undo- procedure [Implementation] returns [Implementation]; 
SetlnputFocus: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, beforeChar: cardinal '177777B]; 
SetlnputFocus: SimpleTextEdit- procedure ( 

f : Field, beforeChar: cardinal * 1 77777B1; 
SetlnputFocus: -TIP- procedure [ 

w: Window.Handle, takeslnput: boolean, newlnputFocus: LosingFocusProc 'nil, 

clientData: LONG pointer 'nil]; 
SetlntegerltemVaiue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, newVaiue: long integer, 

repaint: boolean "true]; 
SetlsCloseLegalProc: -StarWindowShell- procedure [ 

sws: Handle, proc: IsCioseLegaiPrcc]; 
SetltemBox: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, box: Window.Box]; 
SetltemNameWidth: -MenuData- procedure [item: ItemHandle, width: cardinal]; 
SetltemWidth: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, width: cardinal]; 
SetKeyboard: -Afeybodrd/Cey- procedure [keyboard: BlackKeys.Keyboard]; 
SetLlmitProc: -StarWindowShell- procedure [sws: Handle, proc: UmitProc] 

returns [old: UmitProcJ; 
SetLONGINTEGER: -Atom icPro file- procedure [ 

atom: Atom.ATOM, int: long integer]; 
SetManager: ~77P~ procedure [new: Manager] returns [old: Manager]; 
SetMark: -ContainerCache- procedure [cache: Handle, index: cardinal] 

RETURNS [mark: Mark]; 
SetMiddiePusheeCommands: -StarWindowShell- procedure [ 

sws: Handle, commands: MenuOata.MenuHandle]; 
SetMode: -r/PStar- procedure [ 

mode: Mode, modeChangeProc: ModeChangeProc "nil, 

clientData: long pointer 'nil] returns [old: Mode]; 
SetMultipleChoiceitemValue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, 

newVaiues: long descriptor for array cardinal of Choicelndex, 

repaint: boolean "true]; 
SetName: -StarWindowShell- procedure [sws: Handle, name: XString. Reader]; 
SetNamePicture: -StarWindowShell- procedure [ 

sws: Handle, picture: XString. Character]; 
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SetNextOutOfProc: -FormWindow- procedure [ 

window: Window. Handle, Item: ItemKey, nextOutOfProc: NextOutOfProc] 

RETURNS (old: NextOutOfProc]; 
SetNotifyProc: -TVP- procedure [window: Window. Handle, notify: NotifyProcJ 

RETURNS [oldNotify: NotifyProcJ; 
SetNotifyProcForTabie: ~77P- procedure (table: Table, notify: NotifyProcJ 

RETURNS (oldNotify: NotifyProcJ; 
SetParent: -Window— procedure [window: Handle, newParent: Handle] 

RETURNS [oldParent: Handle]; 
SetPlace: -SimpleTextEdit- procedure [f: Field, place: Window.PiaceJ; 
SetPreferredDims: StarWindowSheU— procedure [ 

sws: Handle, dims: Window.OimsJ; 
SetPreferredlnteriorOims: -StarWindowSheUBxtraZ" procedure [ 

sws: StarWindowShell. Handle, dims: Window.OimsJ; 
SetPreferredPlace: -StarWindowShell- procedure [ 

sws: Handle, place: Window.PiaceJ; 
SetReadOnly: -FormWindow- procedure [ 

window: Window. Handle, item: ItemKey, readonly: booleanJ 

RETURNS [old: booleanJ; 
SetReadOnly: -SimpleTextEdit- procedure [f : Field, readonly: booleanJ 

RETURNS (old: booleanJ; 
SetReadOnly: -StarWindowShell- procedure [sws: Handle, yes: booleanJ; 
SetRegularCommands: -StarWindowShell- procedure [ 

sws: Handle, commands: MenuOata.MenuHandleJ; 
Sets: -XCharSets- type = machine dependent{ 

latin, firstUnusedl, iastUnused1(32), jisSymbol 1, jisSymbol2, extended Latin, 

hiragana, katakana, greek, Cyrillic, firstUserKanjil, lastUserKanji 1(47), 

firstLevel 1 Kanji, lastLevel 1 Kanji(79), firstLevei2Kanji. lastLevel2Kanji(1 1 5), 

jSymbol3, firstUserKanji2, lastUserKanji2(126), firstUnused2, 

lastUnused2(160), firstReserv^dl, lastReserved 1 (223), arabic, Hebrew, 

firstReserved2, lastReserved2(237), general Symbols2, generaiSymbolsl, 

firstRendering, lastRendering(2S3), userOefined, selectCode}; 
SetScrollOata: -StarW/ndowS/ie//- procedure [sws: Handle, new: Scroll DataJ 

RETURNS [old: ScrollOataJ; 
SetSelectlon: -FormWindow- procedure [ 

window: Window. Handle, item: ItemKey, firstChar: cardinal *0, 

lastChar: cardinal " 1 77777BJ; 
SetSelection: -SimpleTextEdit- procedure [ 

f: Field, firstChar: cardinal "0, lastChar: cardinal "177777BJ; 
SetShowKeyboardProc: -KeyboardKey- procedure [ShowKeyboardProcJ; 
SetSiblIng: -Window- procedure [window: Handle, newSibling: HandleJ 

returns [oidSibling: HandleJ; 
SetSleeps: -StarWindowShell Extra- procedure ( 

sws: StarWindowShell. Handle, sleeps: booleanJ returns [old: booleanJ; 
SetSource: -ContainerWindow— procedure ( 

window: Window. Handle, newSource: ContainerSource.Handle] 

returns [oldSource: ContainerSource.Handle]; 
SetState: -StarWindowShell- procedure [sws: Handle, state: StateJ; 
SetStreakSuccession: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, new: StreakSuccessionJ 

RETURNS [old: StreakSuccessionJ; 
SetStreakSuccession: -SimpleTextEdit- procedure [ 

f: Field, new: SimpleTextDisplay.StreakSuccessionJ 

RETURNS [old: SimpleTextOisplay.StreakSuccessionJ; 
SetString: -AtomicProfile- procedure [ 

atom: Atom.ATOM, string: XString. Reader, immutable: boolean ^falseJ; 
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SetSwapitemProc: -MenuData- procedure [menu: MenuHandle, new: SwapitemProc] 

RETURNS [old: SwapltemProcl; ■ 
SetTable: -nP- procedure [window: Window.Handie, table: Table] 

RETURNS [oldTable: Table]; 
SetTableAndNotifyProc: -HP- procedure [ 

window: Window.Handle, table: Table "nil, notify: NotifyProc "nil]; 
SetTabieLlnk: -TIP- procedure [from: Table, to: Table] returns [old: Table]; 
SetTableOpacity: -TIP- procedure [table: Table, opaque: boolean] 

returns [oldOpaque: boolean]; 
SetTabStops: -FormWindow- procedure [ 

window: Window. Handle. tabStops: TabStops]; 
SetTextltemValue: -FormWindow- procedure [ 

window: Window. Handle, item: ItemKey, newValue: XString. Reader, 

repaint: boolean 'true]; 
SetTopPusheeCommands: -StarWindowShell- procedure [ 

sws: Handle, commands: MenuOata.MenuHandle]; 
SetTransitionProc: -StarWindowShell- procedure [ 

sws: Handle, new: TransitionProc] returns [old: TransitionProc]; 
SetUseBadPhosphor: -Window- procedure [Handle, boolean] returns [boolean]; 
SetUserAbort: -TIP- procedure [Window.Handlej; 
SetValue: -SimpleTextEdit- procedure [ 

f: Field, string: XString. Reader, repaint: boolean "true]; 
SetVisibility: -FormWindow- procedure ( 

window: Window.Handle, item: ItemKey, visibility: Visibility, 

repaint: boolean "true]; 
SetWindowltemSize: -FormWindow- procedure [ 

window: Window.Handle, windowltemKey: ItemKey, newSize: Window.Dims]; 
ShellEnumProc: -StarWindowShell- type = procedure (sws: Handle] 

returns [stop: boolean "false]; 
ShellFromChild: ~Sta/W/ndowShe//~ procedure [child: Window.Handle] 

RETURNS [Handle]; 
ShellType: -StarWindowShell- type = machine dependent{ 

regular, keyboard, psheet, attention, static, last(15)}; 
Shift: -Display- procedure [ 

window: Handle, box: Window.Box, newPtace: Window.Place]; 
ShiftState: -KeyboardWindow— type = {None, One, Two, Both}; 
ShortLifetime: -BWSZone- procedure returns [uncounted zone]; 
shortUfetime: -BWSZone- uncounted zone; 
ShowKeyboardProc: ~^eyboard^ey~TYPE x procedure; 
Signal: -Containee- signal [ 

msg: XString. Reader "nil, error: error "nil, errorOata: long pointer "nil]; 
Signal: -ContainerSource- signal [ 

code: ErrorCode, msg: XString. Reader "nil, error: error "nil, 

errorOata: long pointer "nil]; 
SimpleDestroyProc: -Context- Destroy ProcType; 
Sin: --XZ./?ea/~ procedure [radians: Number] returns [sin: Number]; 
SizeColumn: -FileContainerSource— procedure 

returns [multipleAttributes ColumnContentslnfo]; 
Skip: -XToken- procedure [ 

h: Handle, data: FilterState, filter: FilterProcType, 

skiplnClass: boolean "true]; 
Ski pM od e : -XTo/cen— type =: {none, whiteSpace, nonToken}; 

SleepOrOestroy: -StarWindowShell- procedure [Handle] returns [Handle]; ^% 
Slide: -Window- procedure [window: Handle, newPlace: Place]; 
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SlideAndSize: -Window- procedure [ 

window: Handle, newBox: Box, gravity: Gravity 'nwj; 
SiideAndSizeAndStack: -Window- procedure [ 

window: Handle, newBox: Box, newSibllng: Handle, newParent: Handle 'nil, 

gravity: Gravity "nwj; 
SlldeAndStack: -Window- procedure [ 

window: Handle, newPlace: Place, newSibling: Handle, newParent: Handle 'nil]; 
SmallPictureProc: -Containee- type a procedure [ 

data: OataHandle 'nil, type: NSFile.Type 'ignoreType, 

normalOrReference: PictureState] returns [smailPicture: XStrlng.Character]; 
SocketNumber: -XFormat- procedure [ 

h: Handle 'nil, socketNumber: System.SocketNumber, format: NetFormat]; 
SortOrder: -XString- type s machine depenoent{ 

standard, Spanish, Swedish, danish, firstFree, null(255)}; 
SourceModifyProc: -ContamerWindow- TYPE « procedure [ 

window: Window. Handle, source: ContainerSource.Handle] 

returns [changelnfo: ContainerSource.Changeinfo]; 
spares: -BWSAttributeTypes- cardinal = 20; 
Speciallndex: -XZ./?ea/~ TYPE 3 natural; 
Spinnaker: -ProductFactoringProducts- Product = 2; 
SqRt: -XLReal- procedure (NumberJ returns [Number]; 
Stack: -Window— procedure [ 

window: Handle, newSibling: Handle, newParent: Handle 'nil]; 
StandardClose: -StarW/ndowS/ie//-- procedure [sws: Handle] returns [Handle]; 
StandardaoseAll: -StarWindowShell- procedure [sws: Handle] returns [Handle]; 
StandardCloseEverything: -StarWindowShell- procedure 

returns [notOosed: Handle]; 
StandardFiit«rState: -XToken- type = array [0.. 1 J of unspecified; 
StandardLimitProc: -StarWindowShell- LimitProc; 
Star: -ProductFactoringProducts- Product = 0; 
State: -StarWindowShell- type * machine dependent{ 

awake, sleeping, dead, last(7)}; 
StatusOfFilt: -ContainerCache- procedure [cache: Handle] 

RETURNS [CacheFillStatus]; 
StopOrNot: -XString- type a {stop, not} "not; 
Store: -Cursor- procedure [h: Handle]; 
StoreCharacter: -Cursor- procedure [c: XChar.Character]; 
StoreNumber: -Cursor- procedure [n: cardinal]; 

StoreTable: -TlPStar- procedure [Placeholder, TlP.Table] returns (TIP. Table]; 
StreakNature: -XC/»ar- TYPE a {leftToRight, rightToLeft}; 
StreakSuccession: -FormWindow—VfPS s SimpleTextOisplay.StreakSuccession; 
StreakSuccession: -S/mp/erextO/sp/ay- TYPE a { 

leftToRight, rightToLeft, fromFirstChar}; 
StreamObject: -XFormat- procedure [sH: Stream.Handle] returns [Object]; 
StreamProc: -XFormat- FormatProc; 

StreamToHandle: -XToken- procedure [s: Stream.Handle] returns [h: Handle]; 
String: -XFormat- procedure [h: Handle 'nil, s: long string]; 
StrlngArray: -XMessage- type a long descriptor for array cardinal of 

XString.ReaderBody; 
StringlntoBuffer: -SimpleTextDisplay- procedure [ 

string: XString. Reader, bufferProc: BufferProc, lineWidth: cardinal '177777B, 

wordBreak: boolean 'true, StreakSuccession: StreakSuccession 'fromFirstChar, 

font: SimpleTextFont.IVIappedFontHandIe "nil] 

returns [lastLineWidth: cardinal, result: Result, rest: XString.ReaderBody]; 
StringlntoWindow: -SimpleTextDisplay- procedure [ 

string: XString. Reader, window: Window.Handle, place: Window.Place, 
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lineWidth: cardinal " 1 11111^, maxNumberOf Lines: cardinal * 1 , 

lineToLineDeltaY: cardinal "0, wordBreak: boolean "true, 

flags: BitBlt.BitBltFlags "LOOPHOLE[42000B]] 

RETURNS [lines: cardinal, lastLineWidth: cardinal]; 
StringOfltem: -ContainerSoune- StringOf ItemProc; 
StringOfltemProc: -Conta/nerSoorce- TYPE = procedure [ 

source: Handle, itemlndex: Itemlndex, stringindex: cardinal] 

returns [XString.ReaderBody]; 
StuffCharacter: -77P- procedure [ 

window: Window.Handle, char: XString.Character] returns [boolean]; 
StuffCurrentSeiection: ~77P~ procedure [window: Window.Handle] 

returns [boolean]; 

StuffResuits: -TIP- procedure [window: Window.Handle, results: Results]; 
StuffSTRING: -TIP- PROCEDURE [window: Window.Handle, string: long string] 

RETURNS [boolean]; 

StuffString: -TIP- procedure [window: Window.Handle, string: XString. Reader] 

RETURNS [boolean]; 

StuffTrashBin: -HP- procedure [window: Window.Handle] returns [boolean]; 
Subtract: -XLReal- procedure [a: Number, b: Number] returns [Number]; 
Subtractltem: -MenuData- procedure [menu: MenuHandle, old: ItemHandle]; 
SubtractPopupMenu: -StarWindowShell- procedure [ 

sws: Handle, menu: MenuOata.MenuHandle]; 
Subtype: -Prototype- type = cardinal; 

Swap: -BlackKeys- procedure [old: Keyboard, new: Keyboard]; 

Swap: -Cursor- procedure [old: Handle, new: Handle]; 

Swap: -SoftKeys- procedure ( 

window: Window.Handle, table: TIP.Table 'nil, 
notifyProc: TIP. Notify Proc "nil, labels: Labels "xxx, 
highlightedKey: cardinal "nullKey, outlinedKey: cardinal "nuilKey]; 

Swap: -StarWindowShell- procedure [ 

new: Handle, old: Handle, poppedProC: PoppedProc "nil]; 

SwapExistingFormWindows: -PropertySheet- procedure [ 
shell: StarWindowShell. Handle, new: Window.Handle, apply: boolean ^true, 
newMenultemProc: MenultemProc "nil, newMenultems: Menultems "LOOPHOLE[0], 
newTitle: XString. Reader "nil, newAfterTakenDownProc: MenultemProc "nil] 
RETURNS [old: Window.Handle]; 

SwapFormWindows: -PropertySheet- procedure ( 

shell: StarWindowShell. Handle, newFormWindowltems: FormWindow.MakeitemsProc, 
newFormWindowltemsLayout: FormWindow.LayoutProc "nil, apply: boolean "true, 
destroyOld: boolean *true, newMenultemProc: MenultemProc "nil, 
newMenultems: Menultems 'LOOPHOLE[01, newTitle: XString. Reader "nil, 
newGiobalChangeProc: FormWindow.GlobalChangeProc "nil, 
newAfterTakenDownProc: MenultemProc "nil] returns [old: Window.Handle]; 

Swapitem: -MenuData- procedure [ 

menu: MenuHandle, old: ItemHandle, new: ItemHandle]; 

SwapltemProc: -MenuData- type x procedure [ 

menu: MenuHandle, old: ItemHandle, new: ItemHandle]; 

SwapMenultem: -Attention- procedure [ 

old: MenuOata. ItemHandle, new: MenuOata.ltemHandle]; 

Switches: -XToken- FilterProcType; 

SyntaxError: -XToken- signal [r: XString.Reader]; 

systemFileCatalog: -BWSFileTypes-- NSFile.Type s 10476B; 

system FontHeight: -SimpleTextDisplay- readonly cardinal; 
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Table: -TIP" type = long pointer to TableObject; 
, TableError: -r/P-TYPE S5 {fileNotFound,badSyntax}; 

TableObject: -HP-- type; 
TabStops: -forniW/ncyow- TYPE = record ( 

variant: SELECT type: TabType FROM . , 

fixed a > [interval: cardinal], 

vary = > [list: long descriptor for array cardinal of cardinal], 
enocase]; 

TabType: -FormWindow- type ■ {fixed, vary}; 
Take: -ContainerSource- TakeProc; 

TakeNEXTKey: -FormWindoW" procedure [window: Window. Handle, item: ItemKey]; 

TakeProc: -Conta/nerSoofce- TYPE a procedure [ 

source: Handle, copyOrMove: Selection.CopyOrMove, 
afterHint: Itemindex * null Item, withinSameSource: boolean 'false, 
changeProc: ChangeProc "nil, changeProcData: long pointer "nil, 
selection: Selection.ConvertProc "nil] returns [ok: boolean); 

Tan: -XLReal- procedure [radians: Number] returns [tan: Number]; 

Target: -Se/ect/orir- TYPE s MACHINE dependent{ 

window, shell, subwindow, string, length, position, integer, interpressMaster, 
file, fileType, token, help, keyboard, interscriptScript, interscriptFragment, 
serialtzedFile, name, firstFree, last( 1023)}; 

textFlags: -D/sp/ay~ BitBltFlags; 
. TextHintActidn:--formW/ndow~ TYPE = {replace, append, nil}; 

TextHintsProc: -Form W/ndow- TYPE a PROCEDURE [ 
window: Window. Handle, item: ItemKey] 

RETURNS ( . ; 

hi nts: long descriptor for array cardinal op XStri ng. ReaderBody, 
freeHints: FreeTextHlntsProc, hintAction: TextHintAction "replace]; 
ThumbFlavor: -StarW/ndowS/ie//~ type = {downClick, track, upCIick}; 
ThumbScrollProc: -StarWindowShell-jypE = procedure ( 

sws: Handle, vertical: boolean, flavor: ThumbFlavor, m: integer, 
outOfN: integer]; 
Ticket: -Containee- TYPE [2]; 
timeOnly: -XTlfme- XStri ng. Reader; 

TIPResults: -S/mp/efextEd/t- procedure [f: Field, results: TIP.Results] 

returns [tookinputFocus: boolean, changed: boolean]; 
TotalOrPartial: -Conta/nerSoorce- TYPE s {total, partial}; 
Trajectory: -Display- procedure ( 

window: Handle, box: Window.Box "xxx, proc: Trajectory Proc, ; 

source: long pointer " nil, bpl : cardinal " 1 6, height: cardinal "16,' 

flags: BitBltFlags "bitFlags, missesChildren: boolean "false, 

brick: Brick *xxx]; 
TrajectoryProc: -Display— type = procedure [Handle] 

returns [Window.Box, INTEGER); 

TransitionProc: -StarW/ndowSAie//- TYPE a PROCEDURE [ 

sws: Handle, state: State); 
Trapezoid: -Oisp/ay- TYPE a RECORD [ 

x: Interpolator, y: integer, w: Interpolator, h: natural]; \ 
TreatNumbersAs: -xr/me-- TYPE a { 

dayMonthYear, monthDayYear, yearMonthOay, yearOayMonth, cfayYearMonth, 

month YearDay}; 

TrimBoxStickouts: -Window- procedure [window: Handle, box: BoxTreturns (Box); 
TTYObject: -Xfomiat- procedure [h: TTY.Handle] RETURNS [Object]; 
TTYProc: -XFormat- FormatProc; 
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Type: -Context- TYPE =s MACHINE DEPeNOENT{ 

all, first, lastAllocated(37737B), last(37777B)}; 
Type: -Cursor- type = machine oepenoent{ 

blank, builseye, confirm, ftpBoxes, hourGlass, lib, menu, mouseRed, pointOown, 
' C ' pbintLeft, pointRight, pointUp, questionMark, scrollDown, scroilLeft, 

scrollLeftRight, scrollRight, scroHUp, scrollUpDown, textPointer, 

groundedText, move, copy, sameASr adjust, row, column, last(255)}; 
UnderdiangedProc: -Window- TYPE s procedure [Handle, Box]; 
Unintelligible: -X77me- error [vicinity: cardinal]; 
UniciueAction : -Se/ect/on- procedure returns [Action]; 
UniqueTarget: -Selection— procedure returns [Target]; 
UniqueType: -Context- procedure returns (type: Type]; 
UniqueType: -Cursor- procedure returns [Type]; 
Units: "UnitConvenion- type = machine dependent{ 
; - In^h, mm, cm, mica, point, pixel, pica, didotPoint, cicero, 

seventySecondOf Aninch, last(1 5)}; 
unknownContext: -XStr/ng- Context; 

UnmapFont: -SimpleTextFontExtra- procedure [SimpleTextFont.MappedFontHandIeJ; 
Unpack: ~XT/me~ procedure [ 

time: System.GreenwichMeanTime "defaultTime, Itp: LTP 'useSystem] 

RETURNS [unpacked: Unpacked]; 
Unpacked: -XTime- type = record [ 

year: [0..4070B1. - 

month: [0.. 11], 

day:[0..31], 

hour: (0..23J; 

minute: [0..591, 
i^nsecond: [0 .59], ^ 

weekday: [0 .6], 
'\^ -%^: boolean, ' 

zone: System. LocalTimeParameters]; 
UhpostedSwapitemProc: -MenuData- SwapltemProc; 
UnsignedDecimai Format: -X/^'ormat- NumberFormat; 
' UhferminatedQuote: -XTb/fen- signal; 

' •Update: -Conta/nerW/ndow- procedure [window: Window. Handle]; 
Uppercase: -XChar- procedure [c: Character] returns [Character]; 
ii^ibQaeGMT: -XTTnie- useThese LTP; 

UserAbort: -TIP- procedure [Window.Handle] returns [boolean]; 

userPassword : -5tarOes/(top- Atom.ATOM; 

useSystem: -X77me-useSystem LTP; 

Valid: -Window- procedure [Handle] returns [boolean]; 

Validate: -Window- procedure [window: Handle]; 

VaiidateReader: -X5tr/ng- procedure [r: Reader]; 

ValidateTree: -Window- procedure [window: Handle "rootWindow]; 

ValidExponent:-Xi/?ea/-TYPE * [.512..511]; 

Value: -Selection- type = record [ 

value: long pointer, 

ops: LONG POINTER TO ValueProcs 'nil, 

context: long unspecified '0]; 
ValueCopyMoveProc: -Se/ect/on- type = procedure [ 

v: ValueHandle, op: CopyOrMove, data: long pointer]; 
ValueFreeProc: -Se/ect/on- type a procedure (v: ValueHandle]; 
ValueHandle: -Se/ect/on- type = long pointer to Value; 
ValueProcs: -Selection- type = record [ 

free: ValueFreeProc "nil, copyMove: ValueCopyMoveProc "nil]; 
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Vani i laArrowScroil : "StarWindowShellf ArrowScrol I Prpc;. , Sj- . &a v 1 
vanillaContext: -XSfrrng- Context; lAX'Ci! .j?jnj'ir 

vanlllaScrollData: -StarWindowSheU- ScrollData; - , ,( \u j ; , ' 
VanillaThumbScroll: rrStarWindowSheU-ThumbScro^iPxpc; .mB.^c 
version: ~aVV54ttnliute7ypes- NSFiie.ExtendedAttributeType 104608; 
Version: -PfotofypeT- TYPE a cardinal; ; , ; ^ .i^i^ Ji^oo- 

VersionCoiumn: "FiieContamerSpurceExtra- procepure > ouoi^ 

RETURNS [attribute FileContainerSourceXoiuninC^fitent^fphN'j ^ 
yiewPointi-ProductFactoringProducts-' Product = 5; . ^ ^^ti; |»rrr^ifT-; 
ViewPointApps: -rPrqductFactoWngP/wyocts- Product,*.^ * syp« iL' 
Visibility: -FomiVU/ndow-^ type ^ ^visible, invisible, Javisibie<3host};', j 
WaitSeconds: ~77P- procedure [seconds: cardinal]; . >. [B^s/'w-'^^-iri 
When: -StaiWmctowS/ie//-- type s {before, after}; > .avTs. f M^b 
White: -0/sp/ay~ procedure ( • ..---•:v vf^i„-%'<-u-- 

window: Handle, box: VVindow.Box, bounds: Window.BoxHand^e 'nil]; 
WhiteSpace: -XToken- FilterProcType; . r , ; • bn ;: >sl v: t £»r 
WordsForBitmapUnder: -Window- proced^f^e [window:- hLandj^l RETuj^ns [cardinal]; 
Writer: -XStr/ng- TYPE = long pointer TO WritfrBody; : soHaem-iU 
WriterBody : -XString- type = private machine DEPENDENT.REi;oRpi -.^ . . :^ 

context(0:0..15): Context, ^ ; --jr-r^.: i^n;: 

limit(1:0.,15): cardinal, ^ . , > :Dv'>;:55n; 



offset(2 : 0. . 1 5) : cardinal. 



bytes(3:0..31): Bytes, ,m\Z^.:y 
maxLimit(5:0.. 15): CARDINAL, r O; i-i:^ ;Qn; 

endContext(6:0.. 15): Context, art i] yi.D 

zone<7:0..31>: UNCOUNTED zone]; fri D] n^or 

WriterBodyFromBlock: ->X5tr/ng~ PROCEDURE [ jek 0] i»ijnirr 

block: Environment-Block, inUse: cardinal '0] returns [WriterBody]; 

WriterBodyFromNSString: -XString- procedure [ c ; ^ ^ w 
s: NSString.String, homogeneous: boolean "false] returns {>A^riterBody]; 

WriterBodyFromSTRING: -XStnng- procedureI'; - J . vi r^ros 
s: long string, homogeneous:. sopLEAN "falseJ returns {V\(riterf ody];j 

Writerlnfo: -XStfing-PRQCEDUfiE [vy: Writer] ^nr < i r rnr>rO; £ U 
RETURNS [unused: cardinal, endContext: Context, zone: uncouimt|D ^^ne]; 

WriterObject: -XFormat- PROCEDURE [w: XString.Write^] returns [Object]; 

WriterProc: -Xf orniat- FormatProc; ^i: 

XFormatObject: -MessageWindow- procedure [yyindow:: WindOiw.Napdle] 



returns [o: XFormat-Object]; 



xorBoxFiags: ~0/sp/ay~ BitBltFiags; , *. :- v is-.ij.ncifc-iifci-u 
xorFlags: -Display- BitBltFlags; " .^^j,.^ -ZJ^.. r;x- Tb;?v?«^2u 
xorGrayFlags: ~D/sp/ay- BitBltFlags; , j -: ^ - v >t;)r /^-^ rbiisV 

zero: ~XL/?ea/- Number; . , r ^ , » v at ? V 

Zone: -Undo- procedure returns [uncounted zone]; . r s; ; : ^^tc hi r * 

■:. ., -. . ■-•v, -^N,- — . \ ' . . -^iVv-- ■ '-l ;3t'"bii ■••V 



#-47 



D Listing of Public Symbols 



D-48 



Viewpoint Programmer's Manual 



77 



name is the name of the table. 

fiiiinByRow determines what happens when the user presses the next key. If fiillnByRow is 
TRUE, pressing the next key advances through the table one row at a time, and the table is 
expanded by rows. In this case, the number of columns is fixed and the number of rows can 
be either fixed or varying. If fiiiinByRow is false, then pressing the next key advances 
through the table one column at a time, and the table is expanded by columns. In this case, 
the number of rows is fixed and the number of columns can be either fixed or varying. 
fixedRows and fixedCoiumns indicate whether the user can change the number of rows 
and columns in the table. 

numberOKolumns and numberOf Rows are used as hints for StartTabie. 

visibleHeader indicates whether there should be a visible header at the top of the table; 
repeatHeader, repeatTopCaption, repeatBottomCaption indicates whether or not to 
repeat these items on every page if the table occupies multiple pages. 

borderline describes the table border (not the frame border), and dividerLine describes the 
line between the header row and the rest of the table. A line can have a width anywhere 
from one pixel to six pixels. 

Line: type ■ record [ 
linestyie: Linestyle, 
iinewidth: Linewidth];. 



Linestyle: type ■ machine dependent{ 

/ft^ — li-i -t — I 1 -i^-^ — I -i^..ui- I 1 .t!— ^A.— I ..A. — :i-ui-/-.gg-\i 



